> ## 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 key.

## API key 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**

  **Note**: If connecting to the MCP Server via OAuth, Omni will automatically create an **MCP OAuth PAT** for the authenticating user. See the [MCP Server authentication documentation](/ai/mcp/authentication#oauth-authentication) for more information.

Use the following table to compare API key types:

|                     | Organization API key                                                                                | Personal Access Token (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                    | Connecting to the MCP Server via OAuth                                                                 |
| **Who can create**  | Organization Admins                                                                                 | Restricted Querier+ users                                                          | Any user                                                                                               |
| **Permissions**     | Organization Admin                                                                                  | Creating user's permissions                                                        | Creating user's permissions                                                                            |
| **Where to create** | [**Settings > API access > Organization keys**](/api/authentication#creating-organization-api-keys) | [**Profile > Manage account > Generate token**](/api/authentication#creating-pats) | 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 - use the [List API tokens endpoint](/api/api-tokens/list-api-tokens) |

## Authorization header

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>'
```

## Organization API keys

<Note>
  **Organization Admin** permissions are required to create and access organization API keys.
</Note>

### Creating Organization API keys

To create an API key:

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

### Enabling and disabling Organization API keys

Organization API keys can be temporarily disabled and re-enabled without revoking them, both in the Omni UI and programmatically via the [Enabling and disabling Organization API tokens endpoint](/api/api-tokens/enable-or-disable-api-token). This allows you to suspend a key's access without permanently deleting it.

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

### Revoking an Organization API key

Unlike disabling an API key, revoking permanently deletes the API key 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).

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

### API key expiration

API keys do not expire, but they may be revoked by the user at any time. In the event that your API key is lost or compromised, delete the API key in your Omni instance and create a new one. API keys 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 key will reflect that change.

## Personal Access Tokens (PAT)

<Tip>
  **Looking for MCP OAuth PATs?** See the [MCP Server authentication documentation](/ai/mcp/authentication#mcp-oauth-pats) for more information.
</Tip>

Personal access tokens (PAT) allow individual users to use the Omni API with their own permissions, rather than using an Organization API key. A PAT is scoped to the user who creates it and will inherit their in-app permissions.

### Inaccessible endpoints

PATs cannot be used for authentication with the following endpoints, as an Organization API key is required:

* [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

### Creating PATs

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

### Enabling and disabling PATs

Organization Admins can disable and re-enable Personal Access Tokens without revoking them, both in Omni and programmatically with the [Enable or disable API token endpoint](/api/api-tokens/enable-or-disable-api-token). This allows you to suspend a token's access without permanently deleting it.

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

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

### Revoking a PAT

Organization Admins can revoke **all** existing PATs by disabling the **Settings > API access > Personal tokens** setting. A confirmation dialog will appear before the setting is disabled to prevent accidental revocation of all user tokens.

Organization Admins can also use the [Delete an API token endpoint](/api/api-tokens/delete-api-token) to revoke PATs.

Individual users can revoke (delete) their PAT by:

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