What Oleria discovers
Once connected, Oleria continuously discovers and maps the following from your Factorial company:-
Employees - every employee Factorial lists, active and terminated. Each employee appears as an account, as an employee record, and as a person.
- The account shows the employee’s sign-in email, or their work email if they have no sign-in email, with their other email addresses as alternates. It also shows their name (using the preferred first name when set), employee number, company name, country, cost center, and creation date.
- The employee record shows work email, employee number, start date, job title, employment type (full time or part time), job level and role, cost center, workplace, company name, and manager. The company name is the employee’s legal entity, or else the company name.
- The person shows the employee’s first and last name and personal email, linked to their employee record.
- An employee is enabled while Factorial reports them as active and their termination date hasn’t arrived. Oleria compares the termination date with today’s date in the time zone of the employee’s workplace, or in UTC when the workplace or its time zone is unknown. The termination date is the account’s expiration date and the employee’s end date. An employee with a termination scheduled for a later date stays enabled until that date.
- When an employee has more than one cost center, Oleria shows the active one with the largest percentage. If two have the same percentage, it shows the one whose cost center assignment has the lower Factorial ID.
- Teams - each Factorial team appears both as a department and as a group. The team’s direct members are its members, and team leads are marked as Lead and shown as the group’s owners. Nested teams appear as nested departments and nested groups. Someone who belongs to a team only through one of its sub-teams is shown as a member of the sub-team, and reaches the parent team through the nesting.
- Workplaces - each Factorial workplace appears as a group named after the workplace. Employees are members of their workplace.
- Legal entities - each Factorial legal entity appears as a group named after its legal name and country. Employees are members of the legal entity that employs them.
- Reporting lines - which employee manages which, used to build your organization hierarchy.
- Non-human identities (NHIs) - every Factorial webhook subscription, shown as an application NHI named after the subscription or its event type. A subscription is enabled when Factorial reports it as enabled. A subscription with a challenge secret also has a client secret credential. Oleria records only that the secret exists, never its value. Factorial doesn’t record who created a subscription, so subscriptions have no owner.
-
Activity - entries from the Factorial employee-updates feed:
- hires;
- terminations;
- changes to an employee’s name, ID, address, IRPF (Spanish income tax) details, bank details, residence, nationality, gender, contract, workplace, or legal entity.
This integration covers your workforce, groups, webhook subscriptions, and activity. It doesn’t read documents, IT assets, or other resources, so Oleria doesn’t populate resource-level Access Graph or Access Inventory data for Factorial. Payroll, compensation, attendance, and time-off balances aren’t read. Personal data is limited to each employee’s personal email and the activity entries listed above.Factorial has no AI agent objects in its API, so none appear. Factorial’s AI assistant and its MCP server act as the signed-in user, so their changes belong to that person’s employee account.
Prerequisites
- A Factorial administrator. Only an administrator can create an API key or an OAuth application.
- Admin access on the Oleria platform to add a new integration.
Choose an authentication method
Factorial permissions
With an API key, Oleria has every scope, and Oleria shows the permission each feature needs as API key (grants all scopes). With OAuth, Oleria requests all of these scopes when you connect, so grant all of them: Factorial may refuse an application that’s missing one. To sync, onlyemployees is required. If Factorial denies Oleria any of the other scopes, Oleria skips that data and syncs everything else. Changing the application’s scopes later means reconnecting (see the note below).
Webhook subscriptions don’t need a scope.
Create the Oleria credential in Factorial
Create either an API key or an OAuth application, depending on the method you chose.API key
1
Sign in as an administrator
Sign in to Factorial as an administrator of the company you want to connect.
2
Create the key
Go to Settings -> API keys, create a key named Oleria, and copy it.
OAuth application
1
Sign in as an administrator
Sign in to Factorial as an administrator of the company you want to connect.
2
Create the application
Go to Settings -> Advanced configuration -> OAuth applications, and create an application with a client secret.
3
Grant the scopes
Grant the application the scopes in Factorial permissions:
employees, company_locations, company_legal_entities, contracts, job_catalog, finance, and employee_updates. Grant all of them: Oleria requests every one when you connect.4
Add the redirect URIs
Add both of these redirect URIs, with your Oleria workspace URL in place of
https://<your-oleria-workspace>. The Oleria connection form shows both, with your workspace URL filled in.https://<your-oleria-workspace>/workspace/integrations/factorial/connect, used when you connect.https://<your-oleria-workspace>/workspace/integrations/edit, used when you reconnect.
5
Copy the client credentials
Copy the application’s Client ID and Client secret.
Factorial invalidates every token an OAuth application has issued when you change the application’s scopes. If you change them later, reconnect the integration.
Connect Factorial to Oleria
1
Open the integration
Go to your Oleria workspace, select Integrations -> select Factorial.
2
Choose the authentication method
In Authentication method, select API key (recommended) or OAuth.
3
Enter the credential
For an API key, enter it in API key. For OAuth, enter the OAuth client ID and OAuth client secret.
4
Authenticate
Select Authenticate. With an API key, Oleria connects directly. With OAuth, you’re redirected to Factorial. Sign in as an administrator of the company you want to connect, and approve access for the company. Factorial returns you to Oleria.
5
Confirm the connection
Before it saves the connection, Oleria checks that:
- Factorial accepts the credential and reports the company it belongs to;
- the credential belongs to the company, not to a single employee;
- Oleria can list the company’s employees.
Reconnect the integration
To change the credential, edit the Factorial integration in Oleria, enter the new API key or OAuth client details, and select Update. With OAuth, you’re redirected to Factorial to approve access again. If you leave a secret blank, Oleria keeps the stored one, unless you switch the authentication method or enter a new client ID. To rotate an API key, create a new key in Factorial, update the integration with it, and then revoke the old key in Factorial. The integration stays bound to the Factorial company it connected to. If the new credential belongs to a different company, Oleria refuses the update and keeps the existing connection. To connect another company, create a new Factorial integration. Oleria also checks the company at the start of every sync. If the credential now belongs to a different company, the sync fails with an error that names both companies and says to reconnect the integration. With OAuth, Oleria refreshes the access token only when it expires, and saves the new refresh token straight away. If saving fails, Oleria keeps using the new tokens and retries the save. Oleria treats each refresh token as single use, so only one refresh runs at a time for a connection. If Factorial rejects the refresh token, the sync fails with an error that says to re-authorize the integration: edit it, select Update, and approve access in Factorial again. If Factorial rejects an access token that hasn’t expired, Oleria doesn’t spend the refresh token. The sync fails with an error that says to retry, and to re-authorize the integration if the error persists.Verify the integration
Confirm the Factorial company appears on the Connected tab of your Oleria Integrations page with a status of Healthy. After the first sync completes, review the discovered employees, teams, workplaces, legal entities, webhook subscriptions, and activity in your Oleria workspace. In the integration’s Capabilities and operation readiness section, Read users and Read groups show Available. Read roles shows as not supported, because Factorial has no roles in its API. Oleria checks each row with a test read:
If Factorial refuses a test read, the row shows Needs permission. Workplaces and legal entities don’t affect Read groups: without their scopes, those groups are skipped.
Remediation actions
Oleria doesn’t take remediation actions in Factorial. Factorial is your HR system of record, so changes such as terminations and team membership belong to your HR process. Make them in Factorial, and Oleria picks them up at the next sync.Pacing
Factorial publishes a limit of 200 POST requests per minute and doesn’t publish one for reads. Oleria paces each connection’s reads at 180 requests per minute in total, shared across the parts of the sync that run at the same time. When Factorial answers that it’s rate limited or has a server error, Oleria waits and retries the read.Known limitations
- No roles or administrators. Factorial manages access through permission groups, which its API doesn’t expose. Oleria can’t show roles, and no employee is marked as an administrator.
- No sign-in data. Factorial’s API doesn’t report MFA, SSO, last sign-in, or password changes, so MFA and SSO show as unavailable, and Oleria doesn’t detect or disable dormant Factorial accounts.
- Audit log not available. Factorial’s audit log is available only in the Factorial interface. Activity comes from the employee-updates feed instead.
- No actor on activity. The employee-updates feed doesn’t say who made the change, so activity isn’t attributed to any account. It doesn’t include an IP address.
- Activity window. When you connect, Oleria reads activity from the start of the sync window, and never more than 365 days back. Each sync checks updates that take effect within about two weeks of when they were recorded; once a week Oleria rechecks the full year. An update dated more than two weeks before it was recorded can take up to a week to appear, and one dated more than about a year before isn’t read.
- External users aren’t visible. Factorial external users, including external administrators, can sign in without being employees, and Factorial’s API doesn’t list them. Review them in Factorial.
- Webhook subscriptions are the only NHIs. Factorial’s API doesn’t list API keys or OAuth applications, so they don’t appear. Oleria’s own credential doesn’t appear either. Factorial describes its webhook subscription list as the subscriptions configured for your credentials, so subscriptions created with another API key or OAuth application might not appear.
- Employment type. Oleria shows Full-Time or Part-Time from the working time on the employee’s current contract. Factorial’s contract types differ by country, so Oleria doesn’t show them. Without the
contractsscope, or when a contract has no working time, the employment type shows as Unknown. - Workplace and legal entity membership. Membership of workplace and legal entity groups comes from each employee’s workplace and legal entity.