Skip to main content

​
API token types

All API requests require authentication using either:
  • Organization API keys - Created by Organization Admins in Settings > API access.
  • Personal Access Tokens (PAT) - User-scoped tokens created in a user’s profile settings. PATs allow individual users to use the Omni API with their own permissions. A PAT is scoped to the user who creates it and will inherit their in-app permissions. Note: If connecting to the MCP Server or CLI through OAuth, Omni will automatically create an OAuth PAT for the authenticating user. See the MCP Server authentication documentation or CLI authentication documentation for more information.

​
API token type comparison

Use the following table to compare API token types:
Organization API keyPersonal Access Token (PAT)CLI OAuth PATMCP OAuth PAT
What’s it forSystems integrations, automated workflows, and API endpoints inaccessible to PATsIndividual user workflows using any PAT-compatible API endpointCLI authentication with OAuthConnecting to the MCP Server with OAuth
Who can createOrganization AdminsRestricted Querier+ usersAny userAny user
PermissionsOrganization AdminCreating user’s permissionsCreating user’s permissionsCreating user’s permissions
Endpoint accessUnlimitedSome restrictionsSame as PATSame as PAT
ExpirationNoneNone8 hours (auto-refreshes)None
Where to createSettings > API access > Organization keysProfile > Manage account > Generate tokenAutomatically created during the CLI OAuth flowAutomatically created during the MCP OAuth flow
Where to viewSettings > API access > Organization keysSettings > API access > Personal tokensNot currently visible in the appNot currently visible in the app - use the List API tokens endpoint

​
PAT endpoint limitations

PATs cannot be used for authentication with the following endpoints: An Organization API key is required to use these endpoints.

​
Authorization header

Include your token in the Authorization header as: Bearer YOUR_API_KEY: 
curl -L 'https://your-omni-org.omniapp.co/api/scim/v2/users' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YOUR_API_KEY>'

​
API token expiration

API token do not expire, but they may be revoked by the user at any time. In the event that your API token is lost or compromised, you can rotate the token for zero-downtime updates, or delete the API token in your Omni instance and create a new one. API token are tied to the current state of the user who created them. If the creator’s user attributes change or the user is revoked, the associated token will reflect that change.

​
Creating API tokens

The steps to create an API token depend on the type of API token. Select the type of your API token from the following tabs to view instructions.
Organization Admin permissions are required to create and access organization API keys.
1
Navigate to Settings > API access > Organization keys.
2
Click Generate new key.
3
In the modal that displays, enter a descriptive name for the API key.Note: API keys will inherit the user attributes of the user who created the key. Enter something that distinguishes you as the creator, such as your initials, into the key’s Name field to make it easy to identify who created the key. This can be helpful when troubleshooting permission issues.
4
Click Generate.
5
Copy the key. Note: API keys are only displayed once when created.

​
Enabling and disabling API tokens

API tokens can be temporarily disabled and re-enabled without revoking them, both in the Omni UI and with the API. This allows you to suspend a tokens’s access without permanently deleting it. Disabled API tokens will remain visible in Omni and in responses from the List API tokens endpoint, but they can’t be used to authenticate until they are re-enabled. The steps to rotate an API token depend on the type of API token. Select the type of your API token from the following tabs to view instructions.
1
Navigate to Settings > API access > Organization keys.
2
In the Organization Keys tab, locate the key you want to work with.
3
Click Disable to disable the token, or Enable to re-enable a disabled token.

​
Rotating API tokens

Rotation is not supported for disabled tokens, already-expired tokens, or OAuth/MCP tokens.
Rotating an API token allows you to generate a new secret without downtime. When you rotate a token, the old secret continues working for a 24 hour grace period, allowing you to update your applications before the old secret expires. During rotation:
  • A new secret is generated and the token retains its original name
  • The old secret remains valid for 24 hours
  • If the token has a finite expiration date, the new token inherits it
The steps to rotate an API token depend on the type of API token. Select the type of your API token from the following tabs to view instructions.
1
Navigate to Settings > API access > Organization keys.
2
Locate the key you want to rotate.
3
Click Rotate in the same row as the API key.
4
When prompted, click Confirm to proceed with the rotation.
5
Copy the new secret. Note: The new secret is only displayed once.
The old secret will continue working for a 24 hour grace period, allowing you to update your applications without disruption.

​
Revoking API tokens

Unlike disabling an API token, revoking permanently deletes the API token from your Omni instance. Tokens can be revoked in the Omni app using the following instructions or with the Delete an API token endpoint. The steps to revoke an API token depend on the type of API token. Select the type of your API token from the following tabs to view instructions.
1
Navigate to Settings > API access > Organization Keys.
2
Locate the API key you want to revoke.
3
Click the (trash can) icon in the same row as the API key.
4
When prompted, click Yes, revoke to confirm.

​
Introspecting token capabilities

The Who Am I endpoint allows you to discover your token’s identity, scope, and permissions without attempting an action. This is useful for CLIs, agents, and client applications that need to determine their capabilities upfront. For example, checking which models a token has access to or whether a token has Organization Admin permissions. See the Who Am I endpoint documentation for more information.