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

# API authentication

> Authenticate your requests to the Omni API with an API token.

<h2 id="token-types">
  API token types
</h2>

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](/ai/mcp/authentication#oauth-authentication) or [CLI authentication documentation](/developers/cli/authentication#oauth-authentication) for more information.

<h3 id="token-comparison">
  API token type comparison
</h3>

Use the following table to compare API token types:

|                     | Organization API key                                                              | Personal Access Token (PAT)                                                 | CLI OAuth PAT                                                                                          | MCP OAuth PAT                                                                                          |
| ------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **What's it for**   | Systems integrations, automated workflows, and API endpoints inaccessible to PATs | Individual user workflows using any PAT-compatible API endpoint             | CLI authentication with OAuth                                                                          | Connecting to the MCP Server with OAuth                                                                |
| **Who can create**  | Organization Admins                                                               | Restricted Querier+ users                                                   | Any user                                                                                               | Any user                                                                                               |
| **Permissions**     | Organization Admin                                                                | Creating user's permissions                                                 | Creating user's permissions                                                                            | Creating user's permissions                                                                            |
| **Endpoint access** | Unlimited                                                                         | [Some restrictions](#pat-endpoint-limitations)                              | Same as PAT                                                                                            | Same as PAT                                                                                            |
| **Expiration**      | None                                                                              | None                                                                        | 8 hours (auto-refreshes)                                                                               | None                                                                                                   |
| **Where to create** | [**Settings > API access > Organization keys**](/api/authentication#create)       | [**Profile > Manage account > Generate token**](/api/authentication#create) | Automatically created during the [CLI OAuth flow](/developers/cli/authentication#oauth-authentication) | Automatically created during the [MCP OAuth flow](/ai/mcp/authentication#oauth-authentication)         |
| **Where to view**   | **Settings > API access > Organization keys**                                     | **Settings > API access > Personal tokens**                                 | Not currently visible in the app                                                                       | Not currently visible in the app - use the [List API tokens endpoint](/api/api-tokens/list-api-tokens) |

### PAT endpoint limitations

PATs cannot be used for authentication with the following endpoints:

* [Document export](/api/content-migration/export-dashboard)
* [Document import](/api/content-migration/import-dashboard)
* [Create email only user](/api/schedule-recipients/manage-email-only-user)
* [Bulk create mail-only users](/api/schedule-recipients/bulk-manage-email-only-users)
* All SCIM **user** & **user group** endpoints

An Organization API key is required to use these endpoints.

<h2 id="auth-header">
  Authorization header
</h2>

Include your token in the `Authorization` header as: `Bearer YOUR_API_KEY`:

```bash {3} theme={null}
curl -L 'https://your-omni-org.omniapp.co/api/scim/v2/users' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YOUR_API_KEY>'
```

<h2 id="expiration">
  API token expiration
</h2>

API tokens 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](#rotate) for zero-downtime updates, or delete the API token in your Omni instance and create a new one.

API tokens 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.

<h2 id="create">
  Creating API tokens
</h2>

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.

<Tabs>
  <Tab title="Organization API key">
    <Note>
      **Organization Admin** permissions are required to create and access organization API keys.
    </Note>

    <Steps>
      <Step>
        Navigate to **Settings > API access > Organization keys**.
      </Step>

      <Step>
        Click **Generate new key**.
      </Step>

      <Step>
        In the modal that displays, enter a descriptive name for the API key.

        **Note**: API keys will inherit the [user attributes](/administration/users/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.
      </Step>

      <Step>
        Click **Generate**.
      </Step>

      <Step>
        Copy the key. **Note**: API keys are only displayed once when created.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Personal Access Token">
    <Steps>
      <Step title="Enable Personal Tokens for your Omni instance">
        First, an **Organization Admin** has to enable the **Settings > API access > Personal tokens** setting. This allows users in the instance to create PATs.
      </Step>

      <Step title="Generate a token">
        Once enabled, users with **Restricted Querier** or higher permissions can create a personal token.

        Click your Omni [user profile icon](/administration/users/your-account), then **Manage account > Generate token**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<h2 id="enable-disable">
  Enabling and disabling API tokens
</h2>

API tokens can be temporarily disabled and re-enabled without [revoking](#revoke) them, both in the Omni UI and with the [API](/api/api-tokens/enable-or-disable-api-token). This allows you to suspend a token's access without permanently deleting it.

Disabled API tokens will remain visible in Omni and in responses from the [List API tokens](/api/api-tokens/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.

<Tabs>
  <Tab title="Organization API key">
    <Steps>
      <Step noAnchor>
        Navigate to **Settings > API access > Organization keys**.
      </Step>

      <Step noAnchor>
        In the **Organization Keys** tab, locate the key you want to work with.
      </Step>

      <Step noAnchor>
        Click **Disable** to disable the token, or **Enable** to re-enable a disabled token.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Personal Access Token">
    <Steps>
      <Step noAnchor>
        Navigate to **Settings > API access > Personal tokens**.
      </Step>

      <Step noAnchor>
        In the **Personal tokens** tab, locate the token you want to work with.
      </Step>

      <Step noAnchor>
        Click **Disable** to disable the token, or **Enable** to re-enable a disabled token.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<h2 id="rotate">
  Rotating API tokens
</h2>

<Note>
  Rotation is not supported for disabled tokens, already-expired tokens, or OAuth/MCP tokens.
</Note>

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.

<Tabs>
  <Tab title="Organization API key">
    <Steps>
      <Step>
        Navigate to **Settings > API access > Organization keys**.
      </Step>

      <Step>
        Locate the key you want to rotate.
      </Step>

      <Step>
        Click **Rotate** in the same row as the API key.
      </Step>

      <Step>
        When prompted, click **Confirm** to proceed with the rotation.
      </Step>

      <Step>
        Copy the new secret. **Note**: The new secret is only displayed once.
      </Step>
    </Steps>

    The old secret will continue working for a 24 hour grace period, allowing you to update your applications without disruption.
  </Tab>

  <Tab title="Personal Access Token">
    <Steps>
      <Step>
        Click your Omni [user profile icon](/administration/users/your-account) in the top right corner.
      </Step>

      <Step>
        Click **Manage account**.
      </Step>

      <Step>
        Locate the **Personal API token** section.
      </Step>

      <Step>
        Click **Rotate**.
      </Step>

      <Step>
        When prompted, click **Confirm** to proceed with the rotation.
      </Step>

      <Step>
        Copy the new secret. **Note**: The new secret is only displayed once.
      </Step>
    </Steps>

    The old secret will continue working for a 24 hour grace period, allowing you to update your applications without disruption.
  </Tab>
</Tabs>

<h2 id="revoke">
  Revoking API tokens
</h2>

Unlike [disabling an API token](#enable-disable), 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](/api/api-tokens/delete-api-token).

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.

<Tabs>
  <Tab title="Organization API key">
    <Steps>
      <Step>
        Navigate to **Settings > API access > Organization Keys**.
      </Step>

      <Step>
        Locate the API key you want to revoke.
      </Step>

      <Step>
        Click the <Icon icon="trash-can" iconType="solid" /> (trash can) icon in the same row as the API key.
      </Step>

      <Step>
        When prompted, click **Yes, revoke** to confirm.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Personal Access Token">
    Organization Admins can revoke **all** user-created PATs by disabling the **Settings > API access > Personal tokens** setting. OAuth-minted tokens (CLI and MCP OAuth PATs) are unaffected. A confirmation dialog will appear before the setting is disabled to prevent accidental revocation of all user tokens.

    To revoke a single PAT:

    <Steps>
      <Step>
        Click your Omni [user profile icon](/administration/users/your-account) in the top right corner.
      </Step>

      <Step>
        Click **Manage account**.
      </Step>

      <Step>
        Locate the **Personal API token** section.
      </Step>

      <Step>
        Click the <Icon icon="trash-can" iconType="solid" /> (trash can) icon.
      </Step>

      <Step>
        When prompted, click **Yes, revoke** to confirm.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<h2 id="whoami">
  Introspecting token capabilities
</h2>

The [Who Am I endpoint](/api/who-am-i) 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](/api/who-am-i) for more information.