> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.instabase.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.instabase.com/_mcp/server.

# Adding OAuth account mappings

> Link AI Hub accounts to identities in your OAuth provider to enable using externally managed API tokens.

Enterprise

Enterprise-tier organizations can use their OAuth provider to manage API access using externally generated tokens. After [configuring an OAuth provider](/admin/security/oauth-providers/), create account mappings to link AI Hub accounts to external identities. When an API request is made with an externally managed token, AI Hub validates the token and extracts the subject claim to identify the account. The request is then authorized based on either:

* The token's scope claim, if present and valid, which [defines role-based permissions for the token](/admin/security/oauth-providers#understanding-scope-permissions).

* Or, if no valid scope is provided, the mapped account's [assigned roles and associated permissions](/admin/roles/).

Admins can add and manage OAuth account mappings.

## Adding account mappings

Adding account mappings is similar for user and service accounts. Each mapping connects an AI Hub account to a unique external account identifier in your OAuth provider. Each account can have one mapping per configured OAuth provider.

> **Before you begin**
>
> Before adding account mappings, ensure you have:
>
> * [Configured an OAuth provider](/admin/security/oauth-providers) for your organization.
>
> * Taken note of external account identifiers for each user or service account you want to map. This identifier must match the value passed in the issued token's subject claim.
>
> > **Note**
> >
> > AI Hub looks for the subject in the `sub` claim, unless [configured otherwise](/admin/security/oauth-providers#claim-mapping).

1. In the header, click the initials icon and select **Settings**. Select the organization name tab.

2. For user accounts, on the **Members** tab, select the user account to map. For service accounts, on the **Service accounts** tab, select the service account to map.

3. In the **OAuth account mappings** section, click **Add mapping**.

4. Add a display name to identify the mapping.

5. Select an OAuth provider configuration.

6. Enter the external account identifier.

7. Click **Add mapping**.

## Updating account mappings

You can update the display name of an account mapping.

> **Note**
>
> The external account identifier and OAuth provider can't be changed for existing mappings. To update these values, delete the mapping and create a new one.

1. In the header, click the initials icon and select **Settings**. Select the organization name tab.

2. Select the **Members** or **Service accounts** tab.

3. Select the user or service account with the mapping to update.

4. In the **OAuth account mappings** section, locate the mapping to update. Click the overflow icon ![Icon with three stacked vertical dots.](/_fern-img/a83e2b40897c8c3871ed84b69fd99d990dbe0eb9bc3936ad84addb6d2ce31f95.webp), then select **Edit mapping**.

5. Make any changes, then click **Update mapping**.

## Deleting account mappings

Deleting an account mapping immediately revokes the ability to use OAuth tokens associated with that external account identifier. Active tokens are invalidated on their next use.

1. In the header, click the initials icon and select **Settings**. Select the organization name tab.

2. Select the **Members** or **Service accounts** tab.

3. Select the user or service account with the mapping to delete.

4. In the **OAuth account mappings** section, locate the mapping to delete. Click the overflow icon ![Icon with three stacked vertical dots.](/_fern-img/a83e2b40897c8c3871ed84b69fd99d990dbe0eb9bc3936ad84addb6d2ce31f95.webp), then select **Delete mapping**.

5. Enter the confirmation text, then click **Delete** to confirm.

> **Tip**
>
> To delete all mappings, navigate to the **OAuth account mappings** section of the account's details page, then click **More** > **Delete all mappings**.