OneLogin Getting Started: Account Setup & First API Call (2026)

Getting started overview

Integrating with OneLogin’s API involves a structured process to ensure secure and efficient identity and access management. This guide outlines the essential steps to get an environment ready for development, from initial account setup to making a successful API call. The core of this process focuses on establishing an administrative account, generating API credentials, and then using those credentials to authenticate requests against the OneLogin API.

Before initiating API calls, developers typically define the scope of their integration, considering whether they need to manage users, applications, or authentication policies. OneLogin's API supports these operations, allowing programmatic access to many of the functionalities available through the administrative console. Familiarity with OAuth 2.0 authorization flows, particularly the client credentials grant type, is beneficial for understanding OneLogin's authentication mechanism.

The following table provides a high-level overview of the steps covered in this guide:

Create an account and get keys

To begin working with the OneLogin API, you must first establish an account and generate the necessary API credentials. OneLogin provides a free trial that offers access to the platform's features, including API capabilities, which is suitable for development and testing purposes.

1. Sign Up for a OneLogin Account

Navigate to the OneLogin sign-up page and follow the prompts to create a new administrator account. This account will serve as your primary access point to the OneLogin administrative interface, where you will manage users, applications, and API credentials.

2. Configure API Access and Create Credentials

Once your account is set up and you've logged into the OneLogin administrator portal, you'll need to enable API access and generate your API credentials. These credentials consist of a Client ID and a Client Secret, which are used to authenticate your application with the OneLogin API using the OAuth 2.0 Client Credentials Grant.

1. From the OneLogin admin dashboard, navigate to Developers > API Credentials.
2. Click the New Credential button.
3. Provide a descriptive name for your API credential (e.g., "My Application API Access").
4. Select the appropriate permissions or roles for this credential. For initial testing, you might choose broad permissions, but in a production environment, adhere to the principle of least privilege. The specific permissions required will depend on the API endpoints you intend to call. For example, to manage users, you would need permissions related to user management.
5. Click Save.
6. OneLogin will display your Client ID and Client Secret. It is critical to copy and securely store these values immediately, as the Client Secret will only be displayed once and cannot be retrieved later. If lost, you will need to generate a new API credential.

These credentials will be used in subsequent steps to obtain an access token, which then authorizes your API requests.

Your first request

After acquiring your Client ID and Client Secret, the next step is to obtain an OAuth 2.0 access token. This token is a temporary credential that authenticates your application for subsequent API calls to OneLogin. The process involves making a POST request to OneLogin's authentication endpoint.

1. Get an Access Token

To get an access token, send a POST request to the OneLogin authentication endpoint (https://api.onelogin.com/auth/oauth/v2/token or your specific regional endpoint). The request body should contain your Client ID, Client Secret, and the grant_type set to client_credentials.

Here’s an example using curl:

curl --location --request POST 'https://api.onelogin.com/auth/oauth/v2/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}'

A successful response will return a JSON object containing your access_token, its token_type (typically bearer), and expires_in (the token's validity duration in seconds).

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 3600,
  "token_type": "bearer"
}

Extract the access_token from this response. This token will be included in the Authorization header of all subsequent API requests.

2. Make an API Call

With the access token in hand, you can now make your first authenticated call to a OneLogin API endpoint. A common starting point is to retrieve a list of users or applications to confirm your authentication is working. For this example, we will query the OneLogin Get Users API endpoint.

Use the access token obtained in the previous step, prefixing it with Bearer in the Authorization header.

curl --location --request GET 'https://api.onelogin.com/api/2/users' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

A successful response will return a JSON array of user objects configured in your OneLogin instance, similar to this (truncated for brevity):

{
  "status": {
    "error": false,
    "code": 200,
    "message": "Success"
  },
  "data": [
    {
      "id": 123456,
      "email": "[email protected]",
      "firstname": "User",
      "lastname": "One",
      "username": "user1"
      // ... more user attributes
    },
    {
      "id": 789012,
      "email": "[email protected]",
      "firstname": "User",
      "lastname": "Two",
      "username": "user2"
      // ... more user attributes
    }
  ]
}

Receiving a list of users indicates that your API credentials are correctly configured and your authentication flow is working.

Common next steps

Once you've successfully made your first API call, you can explore more advanced integrations with OneLogin. The next steps often involve deepening your understanding of specific API functionalities and integrating them into your application logic.

• Explore Specific Endpoints: Review the OneLogin API documentation to identify the endpoints relevant to your use case. This might include managing applications, roles, groups, or configuring multi-factor authentication policies.
• Implement SDKs: OneLogin provides official SDKs in multiple languages, including Python, Ruby, and Node.js. Using an SDK can simplify API interactions by handling authentication, request formatting, and response parsing.
• Error Handling: Implement robust error handling in your application. The OneLogin API returns specific error codes and messages to help diagnose issues. Understanding and responding to these errors is crucial for a resilient integration. The OneLogin API error documentation provides details on common error scenarios.
• Webhooks: For real-time updates on events within OneLogin (e.g., user creation, password changes), investigate OneLogin webhooks. Webhooks allow OneLogin to push notifications to your application when specific events occur, reducing the need for constant polling.
• Security Best Practices: Always adhere to security best practices. This includes securely storing API credentials (e.g., using environment variables or a secret management service), rotating access tokens as recommended, and validating input data for API requests. Review the OneLogin security guidance for more information.
• Production Deployment: Plan for deploying your integration to a production environment. This often involves setting up separate API credentials with tightly controlled permissions, monitoring API usage, and ensuring your application can scale to handle expected load.

Troubleshooting the first call

Encountering issues during your initial API calls is common. Here's a guide to troubleshooting some frequent problems:

401 Unauthorized

This is the most common error and typically indicates an issue with your authentication. Verify the following:

• Expired Access Token: Access tokens have a limited lifespan (expires_in from the token response). If your token has expired, you need to request a new one.
• Incorrect Access Token: Ensure you are using the exact access_token received from the OAuth endpoint, without any extra spaces or characters.
• Missing Bearer Prefix: The Authorization header must be formatted as Authorization: Bearer YOUR_ACCESS_TOKEN. Double-check the Bearer prefix and the space after it.
• Invalid Client ID/Secret: When requesting the access token, ensure your client_id and client_secret are correct and match the ones generated in the OneLogin admin console.

403 Forbidden

A 403 error means your authenticated request lacks the necessary permissions to perform the requested action. This often occurs if:

• Insufficient API Credential Permissions: The API credential you generated might not have the required roles or scopes to access the specific endpoint or perform the action. Review the permissions assigned to the API credential in the OneLogin admin console (Developers > API Credentials > [Your Credential Name]) and compare them against the OneLogin API documentation for required permissions for the endpoint you are calling.
• IP Address Restrictions: Some OneLogin accounts may have IP address restrictions configured for API access. Ensure your originating IP address is whitelisted if such restrictions are in place.

404 Not Found

A 404 error usually indicates that the endpoint or resource you are trying to access does not exist or the URL is incorrect.

• Incorrect Endpoint URL: Double-check the API endpoint URL against the official OneLogin API documentation. Ensure correct spelling, versioning (e.g., /api/2/), and regional domain (e.g., api.onelogin.com).
• Resource Not Found: If you are requesting a specific resource (e.g., /users/<user_id>), ensure the ID or identifier is valid and the resource actually exists in your OneLogin instance.

Other HTTP Status Codes

• 5xx Server Errors: These indicate a problem on OneLogin's side. While less common, if you encounter a 5xx error, it's advisable to check the OneLogin Status Page for any ongoing service issues.
• Request Body/Header Issues: Ensure your Content-Type header is correctly set (e.g., application/json for JSON bodies) and that the request body syntax is valid JSON if applicable.

When troubleshooting, review the full error response from the API, as it often contains specific details that can help pinpoint the problem. Using a tool like Mozilla Developer Network's HTTP status code reference can also provide general context on HTTP errors.