Skip to main content

​
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. 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

The workflow surface is generated from the OneLogin API v2 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 for full details.
1

Log in to your OneLogin admin console

You need admin access to create API credentials.
2

Navigate to Developers > API Credentials

This is where OneLogin manages API credential pairs.
3

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.
4

Click Save

OneLogin generates the credential pair.
5

Copy the Client ID and Client Secret

Keep them somewhere safe until you finish connecting in Serval.
The Client Secret is only shown once, at creation time. If you lose it, you will need to create a new credential.
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.

​
Connect in Serval

1

Open the OneLogin integration in Serval

Find OneLogin in the Serval integrations list and open the connect form.
2

Subdomain (required)

“Your OneLogin domain, e.g. acme.onelogin.com. Do not include https://.” Leaving it blank shows “This field is required”.
3

Client ID (required)

“API credentials Client ID. Generate one in OneLogin under Developers > API Credentials.” Leaving it blank shows “This field is required”.
4

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.
5

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.
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).
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.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.
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.
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.
Need help? Contact support@serval.com for assistance with your OneLogin integration.