> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OneLogin

> Connect Serval to OneLogin to sync users, applications, and roles, and to provision access by managing OneLogin role membership.

## About OneLogin

OneLogin is an identity and access management (IdP) platform. Serval connects to your OneLogin account using an API credentials pair scoped to your OneLogin subdomain and works against the OneLogin API v2. Once connected, Serval keeps your user directory, application catalog, and roles (including who belongs to each role) in sync, and can grant or revoke access by adding or removing users from OneLogin roles. This integration is currently in beta.

**Authentication:** OAuth 2.0 client credentials - you paste a Subdomain, Client ID, and Client Secret from a OneLogin API credentials pair. There is no browser sign-in step.

**Data sync:** Background syncs pull users every 4 hours, and applications and roles every 48 hours (role and membership changes are also picked up by a faster 4-hour delta sync between full role syncs). Access changes run on demand from workflows.

## What the OneLogin integration enables

| Capability                 | Description                                                                                                                                                                                                                                                                   |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User sync                  | Imports your full OneLogin user directory every 4 hours, including email, first and last name, manager, and active status. Users whose OneLogin status is anything other than Active are marked deactivated in Serval.                                                        |
| App sync                   | Imports your OneLogin application catalog every 48 hours, including app names and icons, and links each app to the OneLogin roles that grant access to it.                                                                                                                    |
| Role (group) sync          | Imports OneLogin roles as Serval groups - a full sync every 48 hours plus a 4-hour delta sync - along with each role's members. Roles serve as the group source for this integration, and membership is the single entitlement on each role ("Member of this OneLogin role"). |
| Access management          | Adds or removes a user from a OneLogin role on demand from workflows. The target user is matched by their email address.                                                                                                                                                      |
| Custom workflow API access | Workflows can call the integration's typed OneLogin API v2 operations - users (including a user's apps and roles), roles (including a role's members, admins, and apps), and applications (including an app's users) - with automatic retry and rate-limit handling built in. |

The workflow surface is generated from the [OneLogin API v2](https://developers.onelogin.com/api-docs/2/getting-started/dev-overview) definitions for the user, role, and application endpoints listed above.

## Get your credentials

Serval authenticates with an API credentials pair (Client ID and Client Secret) created in your OneLogin admin console. See OneLogin's guide to [working with API credentials](https://developers.onelogin.com/api-docs/2/getting-started/working-with-api-credentials) for full details.

<Steps>
  <Step title="Log in to your OneLogin admin console">
    You need admin access to create API credentials.
  </Step>

  <Step title="Navigate to Developers > API Credentials">
    This is where OneLogin manages API credential pairs.
  </Step>

  <Step title="Click New Credential">
    Give it a name (e.g. Serval) and pick a scope: **Read all** for sync-only, **Manage all** if Serval will add and remove users from roles.
  </Step>

  <Step title="Click Save">
    OneLogin generates the credential pair.
  </Step>

  <Step title="Copy the Client ID and Client Secret">
    Keep them somewhere safe until you finish connecting in Serval.
  </Step>
</Steps>

<Warning>
  The Client Secret is only shown once, at creation time. If you lose it, you will need to create a new credential.
</Warning>

<Note>
  The scope you pick here determines everything Serval can do. **Read all** is enough for syncing users, apps, and roles. Choose **Manage all** if you want Serval to provision access by changing role membership.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the OneLogin integration in Serval">
    OneLogin is marked as beta in the connect screen.
  </Step>

  <Step title="Subdomain (required)">
    "Your OneLogin domain, e.g. `acme.onelogin.com`. Do not include https\://." Leaving it blank shows "This field is required".
  </Step>

  <Step title="Client ID (required)">
    "API credentials Client ID. Generate one in OneLogin under Developers > API Credentials." Leaving it blank shows "This field is required".
  </Step>

  <Step title="Client Secret (required)">
    "API credentials Client Secret". Entered as a password field. This field has no inline blank-field message - submitting without it fails with a generic "Failed to install integration" error, so paste the secret before you submit.
  </Step>

  <Step title="Submit">
    Click **Submit**. Serval exchanges the Client ID and Client Secret for an access token against your subdomain and uses it for all OneLogin requests.
  </Step>
</Steps>

When you later edit the connection, Subdomain and Client ID come back pre-filled with their saved values, and the saved Client Secret displays obfuscated (bullets plus its last 4 characters) with a control to replace it. Any field you leave blank - and a secret left as its obfuscated placeholder - keeps its existing saved value, so you can rotate just the secret without re-entering the Subdomain or Client ID.

## Verifying the connection

The integration ships four health checks you can run from the integration's page in Serval.

**Test OneLogin Connection** - verifies the integration is configured correctly and can authenticate against the OneLogin API with a minimal read-only call.

* Success: "Successfully authenticated with OneLogin"
* Failure: "Unable to connect to OneLogin." followed by a hint - "The OneLogin client credentials are invalid or expired. Verify the client ID and client secret in the integration settings." (bad credentials), "The OneLogin API credential lacks the required scope. Use 'Read all' for sync-only, or 'Manage all' if access management is needed." (insufficient scope), or "OneLogin returned a server error. This is likely a temporary issue with OneLogin's API - please try again later." (OneLogin-side errors). Other errors show the base message alone.

**List OneLogin Users** - checks that Serval can list users from your directory. Success: "Successfully listed \[number] users from OneLogin"

**List OneLogin Roles** - checks that Serval can list roles. OneLogin "Roles" are the equivalent of "User Groups" in other IdPs. Success: "Successfully listed \[number] roles from OneLogin"

**List OneLogin Applications** - checks that Serval can list applications. Success: "Successfully listed \[number] applications from OneLogin"

The three list checks fail with "Unable to list users from OneLogin." / "Unable to list roles from OneLogin." / "Unable to list applications from OneLogin." followed by a hint - "OneLogin rejected the request as unauthenticated. Check the client ID and secret." (bad credentials), "OneLogin denied the request. The API credential may not have the required scope." (insufficient scope), or "The OneLogin resource was not found. This may indicate an incorrect subdomain or missing permissions." (often a wrong Subdomain).

<Tip>
  All four health checks only need read access, so every check can pass with a **Read all** credential while adding or removing users from roles still fails with permission errors. If syncs look healthy but access changes fail, recreate the credential with **Manage all** scope.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="OneLogin Roles are groups; OneLogin Groups are not synced">
    In OneLogin, "Roles" are what most identity providers call user groups - users gain application access via role membership, and Serval models OneLogin roles as group resources with a single Member entitlement. OneLogin "Groups" are security policies and are intentionally not modeled in Serval. Do not expect OneLogin Groups to appear as Serval resources.
  </Accordion>

  <Accordion title="Permissions come from the credential's scope, not from Serval">
    Serval requests no scopes of its own during authentication - effective permissions come entirely from the scope assigned to the API credential in OneLogin. Use **Read all** for sync-only, or **Manage all** if access management is needed. A credential with too narrow a scope produces permission-denied errors on health checks and syncs.
  </Accordion>

  <Accordion title="The Subdomain is your full onelogin.com domain">
    The Subdomain field expects the full OneLogin domain (e.g. `acme.onelogin.com`) without https\://. Serval only attaches credentials to requests going to a domain of the form `yoursubdomain.onelogin.com`, so a custom branded domain outside onelogin.com will not work. Authentication is also performed against this value, so a wrong Subdomain breaks the connection entirely - "not found" hints on health checks often indicate an incorrect Subdomain.
  </Accordion>

  <Accordion title="Adding or removing access requires a unique email match">
    When a workflow adds or removes a user from a role, Serval finds the user's OneLogin account by exact email match. If no account matches, the workflow fails with "No OneLogin user found with email: \[email]"; if more than one matches, it fails with "Multiple OneLogin users found with email: \[email]". Each person must have exactly one OneLogin account whose email matches their Serval email.
  </Accordion>

  <Accordion title="Updating credentials: blank fields keep their saved values">
    On the update form, every field comes back pre-filled and the Update button stays disabled until you change something. Any field you clear and submit blank (or a Client Secret left as its obfuscated bullet placeholder) keeps the existing stored value - the saved secret displays as bullets plus its last 4 characters, with a control to replace it. This means you can rotate just the secret without touching the Subdomain and Client ID, but it also means clearing a field does not delete the saved value.
  </Accordion>

  <Accordion title="Rate limits and temporary errors are retried automatically">
    Serval automatically retries OneLogin requests that fail with timeouts, rate limits, or temporary server errors. When OneLogin rate-limits a request, Serval waits until the time OneLogin specifies before retrying; otherwise it backs off with increasing delays. Persistent server errors generally indicate a OneLogin-side issue - wait and try again later.
  </Accordion>

  <Accordion title="Paginating OneLogin results in custom workflows">
    OneLogin returns the next-page token in a response header, which must be passed back as a cursor on the next request - and OneLogin rejects requests that combine a cursor with other pagination settings, so a page-size limit should only be sent on the first request. In custom workflows, use the "OneLogin API request with headers" action, which exposes response headers, to paginate; the plain "OneLogin API request" action discards headers and cannot fetch subsequent pages. See OneLogin's notes on [pagination](https://developers.onelogin.com/api-docs/2/getting-started/using-query-parameters#pagination).
  </Accordion>

  <Accordion title="This integration is in beta">
    OneLogin is flagged as beta in the Serval connect screen. Core sync and access management work as described, but expect the integration to continue evolving.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your OneLogin integration.