OneLogin API Essential Guide

What type of API does OneLogin provide?

Based on the search results, OneLogin has a REST API. Here are the key points:

1. OneLogin's API is RESTful.

2. The API is based on RESTful principles, is secured by OAuth 2.0, and provides JSON messages, search, pagination, sorting, and filtering.

3. The API allows customers and integrators to programmatically manage users in OneLogin.

4. The API documentation is available on OneLogin's developer site and contains examples of how to experiment with the API from the command line.

5. API access is available on all paid OneLogin plans.

Key considerations:

• REST APIs are popular for building APIs consumed by web or mobile applications.
• They are based on the principles of resources and HTTP methods, typically using JSON or XML as the data format.
• REST APIs are generally simpler to implement and use compared to other API types like SOAP.

In summary, OneLogin provides a RESTful API that allows programmatic management of users and follows standard REST principles like using JSON, OAuth 2.0 authentication, and features like search and pagination. This type of API is well-suited for integration with web and mobile applications.

Does the OneLogin API have webhooks?

Yes, the official OneLogin API does have webhooks. Here are the key points about OneLogin's webhook functionality:

Webhook Support

• OneLogin offers an Event Webhook API, also known as the Event Broadcaster.
• It sends batches of events in near real-time to an endpoint that you specify.

Event Types

You can subscribe to various types of events, including:

• User login success (event_type_id=5)
• User login failed (event_type_id=6)
• User logout (event_type_id=7)
• User logged into an app (event_type_id=8)
• User changed password (event_type_id=11)
• User added an MFA device (event_type_id=22)

Setting Up Webhooks

• Webhooks need to be set up via the OneLogin Admin portal under Developers > Webhooks.
• There isn't currently an API for setting up the webhook endpoint subscription.

Webhook Payload

• The webhook sends an array of Event objects as a POST request to your registered endpoint.
• Each event object contains detailed information about the event, including user IDs, timestamps, IP addresses, and more.

Filtering Events

• The webhook sends all event types, so you'll need to filter for the specific events you're interested in.
• Filtering can be done based on event_type_id and other attributes like risk_score.

Best Practices

• Use custom headers when configuring your Event Broadcaster to add security and verify request authenticity.
• Your endpoint must respond with an HTTP 200 status code to acknowledge successful receipt of the webhook payload.

In summary, OneLogin's API does support webhooks, allowing you to subscribe to a wide range of event types related to user authentication, login activities, and account changes. This enables real-time monitoring and response to important events in your OneLogin environment.

Rate Limits and other limitations

Here are the key points about the API Rate Limits for the OneLogin API:

Rate Limit Details

• There is an account level rate limit of 5,000 calls per hour, regardless of how many access tokens you have.

• If an access token surpasses this limit, API calls will return an error.

• After the hour has passed, the count will be reset to a full 5,000 available calls.

Checking Rate Limit Status

You can check your current rate limit status by making a GET request to:

https://<subdomain>/auth/rate_limit

This will return the following information:

• X-RateLimit-Limit: Displays the rate limit itself (5000)
• X-RateLimit-Remaining: Displays the remaining calls available for the hour
• X-RateLimit-Reset: Displays the remaining time in seconds before the rate limit is reset

Key Considerations

• The rate limit is at the account level, not per access token.

• Free/Developer accounts are limited to 5000 API calls per hour.

• Paying customers may be able to contact OneLogin support to get their rate limit increased.

• If you exceed the rate limit, you'll need to wait for the hour to pass before making more calls.

Best Practices

• Monitor your API usage to avoid hitting the rate limit unexpectedly.

• Implement proper error handling for rate limit errors.

• If you consistently need more than 5000 calls per hour, consider upgrading your account or contacting OneLogin support.

• Use the rate limit checking endpoint to proactively manage your API usage.

Latest API Version

The most recent version of the OneLogin API is version 2. Here are the key points about the OneLogin API versioning:

API Versioning

• The version number for the OneLogin API is indicated in the URL.
• Versioning starts at 1 and increases as major changes are made to any of the APIs or their payloads.
• It is recommended to always use the latest version.

Current API Versions

• Different API endpoints may be on different versions. For example:
  • Get Users API is currently on version 1: GET /api/1/users
  • Get Apps API is on version 2: GET /api/2/apps

OpenID Connect API

• For the OpenID Connect API, the latest version is v2.0.
• The recommended issuer endpoint for v2.0 is: https://<subdomain>.onelogin.com/oidc/2

API Deprecation

• Version 1 of the OpenID Connect provider was deprecated and no longer available as of April 20th, 2021.

Best Practices

• It is recommended to use the newest version of the API if available, and version /1 in all other cases.
• The newer versions are based on RESTful principles, secured by OAuth 2.0, and provide JSON messages, search, pagination, sorting, and filtering.

In summary, while different endpoints may be on different versions, the most recent overall version of the OneLogin API is version 2, with some endpoints still on version 1. It's important to check the specific endpoint you're using to determine its current version.

How to get a OneLogin developer account and API Keys?

1. Sign up for a free developer account:

   • Go to https://www.onelogin.com/free-trial
   • Fill out the form with your information
   • Your sitename will become your OneLogin subdomain (e.g. mycompany.onelogin.com)
   • Submit the form to create your account

2. Set up your administrator account:

   • You'll receive an email with instructions to create your admin user account
   • Follow the steps to set up your admin credentials

3. Log in to your OneLogin admin portal:

   • Go to <your-subdomain>.onelogin.com/admin
   • Log in with your admin credentials

4. Create API credentials:

   • Go to Developers > API Credentials in the admin portal
   • Click "New Credential"
   • Give your credential pair a meaningful name
   • Select the appropriate API scope (e.g. "Read All" or "Manage All")
   • Save to generate your client ID and client secret

5. Make note of your API credentials:

   • Save the client ID and client secret that are generated
   • You'll need these to authenticate and make API calls

What can you do with the OneLogin API?

Here's the markdown text with the trailing list of URLs and citation references removed, and any URLs inside the content formatted correctly for the markdown file format:

Users

• Get Users
• Get User by ID
• Create User
• Update User
• Delete User
• Set Password
• Set Custom Attribute Values
• Set User State
• Log User Out
• Lock User Account

Apps

• List Apps
• Get App
• Create App
• Update App
• Delete App
• Get Apps for a User

Roles

• Get Roles
• Get Role by ID
• Assign Roles to a User
• Remove Roles for a User

Groups

• Get Groups
• Get Group by ID

Events

• Get Events
• Get Event Types
• Get Event by ID

Multi-Factor Authentication (MFA)

• Get Available Factors
• Enroll a Factor
• Get Enrolled Factors
• Activate a Factor
• Verify a Factor
• Generate MFA Token

Custom Login Pages

• Log in User via API
• Create Session Login Token
• Verify Factor

SAML Assertions

• Generate SAML Assertion
• Verify Factor

Invites

• Generate Invite Link
• Send Invite Link

Embed Apps

• Embed Apps functionality

Other

• Connectors (List Connectors)
• OAuth 2.0 Tokens (Generate, Refresh, Revoke)
• Custom Attribute Fields

Key points to consider:

• The API is RESTful and secured by OAuth 2.0
• It provides JSON messages, search, pagination, sorting, and filtering capabilities
• The API uses your subdomain as the API Domain (e.g., <subdomain>.onelogin.com)
• There are various endpoints available for different operations on these data models