> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # Factorial > Connect Factorial to Oleria to bring your employees, teams, workplaces, legal entities, and webhook subscriptions into your identity graph as the authoritative worker record, with the employee-updates feed as activity. Connect Factorial to Oleria to use your HR system as the authoritative worker record. Oleria reads your Factorial company's employees, teams, workplaces, legal entities, reporting lines, and webhook subscriptions, so a leaver who still holds access in another application is visible. You connect with a Factorial API key or with an OAuth application you create in Factorial. Oleria only reads from Factorial. It doesn't change your HR records. ## 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. Oleria keeps every other entry too, such as leave and incidences, under its Factorial update type. Each entry is linked to the employee's account, and keeps its status and its start and end dates. Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model). > [!NOTE] > > 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. You don't need a dedicated service account. Oleria connects as your Factorial company, not as a person: an API key and an OAuth company authorization both belong to the company. The administrator only creates the credential. Oleria checks that the credential belongs to the company when you connect. Each integration connects one Factorial company. If you have more than one, add an integration for each. See [Multi-instance support](/integrations/overview.md#multi-instance-support). Oleria connects to Factorial's production service. Factorial demo environments aren't supported. ## Choose an authentication method | Method | Use it when | | :- | :- | | **API key (recommended)** | You want the quickest setup. An administrator creates the key in Factorial. A Factorial API key always grants every scope, and doesn't expire until it's revoked. | | **OAuth** | Your policy doesn't allow a credential that holds every scope. You create an OAuth application in Factorial, limited to the scopes below. Factorial grants each scope as read and write. | > [!WARNING] > > A Factorial API key always holds every scope, including the ones that change employees. There's no read-only API key. Oleria only reads, but the key can do anything in your company, so store and rotate it with care. > > OAuth narrows the credential to the seven areas below, but Factorial scopes grant both read and write, so the OAuth application can still change employees, teams, and contracts. Store its client secret with the same care. ## 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, only `employees` 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). | Scope | Used for | | :- | :- | | `employees` | Reading employees, teams, and team members. Required to connect. | | `company_locations` | Reading workplaces: the workplace groups, each employee's country and workplace, and the workplace time zone used for status and termination dates. Without it, no workplace groups sync, and dates use UTC. | | `company_legal_entities` | Reading legal entities: the legal entity groups and each employee's company name. Without it, no legal entity groups sync. | | `contracts` | Reading each employee's current contract for job title, start date, and employment type. | | `job_catalog` | Reading job levels and roles. Needs `contracts` too, because each employee's level comes from their current contract. | | `finance` | Reading cost centers. | | `employee_updates` | Reading activity, and finding terminated employees that Factorial's employee list leaves out. Without it, no activity syncs and those former employees can be missed. | 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](#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://`. The Oleria connection form shows both, with your workspace URL filled in. * `https:///workspace/integrations/factorial/connect`, used when you connect. * `https:///workspace/integrations/edit`, used when you reconnect. **5. Copy the client credentials** Copy the application's **Client ID** and **Client secret**. > [!NOTE] > > 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. Oleria records the Factorial company the credential belongs to. Find the newly connected company on the **Connected** tab of your Oleria **Integrations** page, named **Factorial** followed by the company name. ## 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: | Row | Permission | Test read | | :- | :- | :- | | Read users | `employees` | Employees | | Read groups | `employees` | Teams and team members | 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 `contracts` scope, 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. ## Contact us For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.