Configuring OAuth providers

Enterprise-tier organizations can use their OAuth provider to manage API access using externally generated tokens. Configuring an OAuth provider enables secure authorization for AI Hub API access following OAuth 2.0 standards. When you configure an OAuth provider, AI Hub validates tokens issued by your provider instead of generating its own tokens.

Admins can add and manage OAuth provider configurations. You can add multiple configurations for your organization.

Configuration overview

Adding an OAuth provider configuration involves creating OAuth application registrations in your OAuth provider, then adding configuration details to AI Hub. You then create account mappings in AI Hub to link app registrations in your OAuth provider to AI Hub user or service accounts, enabling token-based API authentication.

When a mapped account makes an API request using an externally managed token:

1. An access token is requested from the OAuth provider.

2. The OAuth provider issues an access token in the form of a JSON web token (JWT).

3. The token is included in the AI Hub API request as the bearer token.

4. AI Hub validates the token signature, issuer, audience, and expiration.

5. AI Hub looks up the account mapping using the token’s subject claim.

6. AI Hub authorizes the request based on either:

   • The scope claim, if present and valid, which defines the token’s permissions using role UUIDs.

   • Or, if no valid scope is provided, the mapped account’s assigned roles and associated permissions.

AI Hub supports flexible OAuth configurations. You can add multiple OAuth provider configurations to your organization, and each user or service account can have multiple account mappings (one per OAuth provider configuration). The number of app registrations you create in your OAuth provider is up to you—AI Hub only requires that each account mapping has a unique subject claim value.

OAuth provider configuration requirements

Review the following requirements for your app registration. The registration process varies by provider. Refer to your OAuth provider’s documentation for specific setup steps.

• Audience — The audience identifies the intended recipient of the token (AI Hub). AI Hub provides a suggested audience value in the format api://<organization-id>.<aihub-environment-url> (such as api://company.aihub.instabase.com), or you can define a custom one. Regardless, the audience value defined in your provider and AI Hub must match exactly.

• Token claims — Each token must contain claims identifying the subject, expiry, and audience. AI Hub expects these values in the sub, exp, and aud claims, respectively. Tokens can also include an optional scp claim that controls token permissions. You can use custom claims for subject, expiry, and scope; audience must be passed under aud.

Claim mapping

AI Hub expects tokens to include required information in the sub, exp, and aud claims and can optionally include a scp claim. While the aud claim must be used, you can use custom claim names for the others. To let AI Hub know which custom claims to look at, you use claim mapping. If using custom claims, be sure the passed values meet the expected format and requirements.

Understanding scope permissions

The scope claim uses role UUIDs to control token permissions. Each API endpoint requires specific actions, and each role UUID grants a set of action permissions. Permission sets correspond to organization and workspace roles. When a scope value is set, it overrides the mapped account’s AI Hub-assigned roles for that token. When the scope claim is omitted or empty, the token uses the mapped account’s roles.

AI Hub validates that all scope entries are known prebuilt role UUIDs. The following table lists common organization and workspace role UUIDs:

There is important behavior to understand when assigning roles through the scope claim:

• All tokens must include an organization role. Only defining a workspace role is invalid. As best practice, limit the number of tokens with organization admin access. Unless necessary, use the organization member UUID alongside workspace role UUIDs.

• The most permissive role applies. The effective permissions are the union of permissions granted by all included roles. For example, a scope that includes both the organization member and workspace developer role UUIDs grants organization member permissions plus all workspace developer permissions in eligible workspaces.

• Both a workspace role and workspace access are required for workspace-scoped actions. A scope claim containing a workspace role alone doesn’t authorize workspace access. For a token to successfully perform a workspace-scoped action, such as running a deployment, the mapped account must be a member of the workspace and have a valid workspace role there.

• The scope applies to all accessible workspaces. When using the scope claim, roles apply across all workspaces where the account is a member. You can’t assign different workspace roles per workspace through scope.

AI Hub configuration requirements

When adding your OAuth provider configuration in AI Hub, you must provide configuration details from your app registration.

• Audience — The audience value that identifies AI Hub as the intended recipient of tokens. By default, AI Hub pre-fills this field with a suggested value in the format api://<organization-id>.<aihub-environment-url> (such as api://your-org.instabase.com). You can accept this value or, if you used a custom value in your OAuth provider configuration, edit the field.

• Discovery endpoint URL — The OpenID Connect discovery endpoint URL, such as https://<YOUR-PROVIDER-DOMAIN>/.well-known/openid-configuration. This endpoint provides the issuer and JSON web key set (JWKS) URLs automatically and is the recommended approach. If your provider doesn’t support OpenID Connect discovery, you can manually provide the issuer and JWKS URLs instead.

  • Issuer URL — The OAuth provider’s issuer identifier, such as https://<YOUR-PROVIDER-DOMAIN>/.

  • JWKS URL — The JSON web key set endpoint URL used to validate token signatures, such as https://<YOUR-PROVIDER-DOMAIN>/.well-known/jwks.json.

Adding OAuth provider configurations

1. In the header, click the initials icon and select Settings. Select the Identity & access tab.

2. Under Externally managed API authorization, click Add configuration.

3. Add a display name to identify the configuration.

4. Select an OAuth provider. Select Custom if your provider isn’t listed.

5. Provide the discovery endpoint URL to allow AI Hub to look up the issuer URL and JWKS URL. Or, click Configure with issuer URL and JWKS URL to define these values yourself.

6. Review or update the Audience value. If accepting the suggested value, proceed. If you defined a custom audience value in your provider configuration, edit the field. The audience values configured in your OAuth provider and AI Hub must match exactly.

7. (Optional) Configure claim mappings if your OAuth provider configuration uses custom claim names.

   • Subject — The claim containing the unique external account identifier. Default sub.

   • Expiration — The claim containing the token expiration time. Default exp.

   • Scope — The claim containing the token scope. Default scp.

8. Click Save.

You can now test your configuration by creating an account mapping and making a test API request.

Testing OAuth provider configurations

Your configuration doesn’t undergo automatic validation, so it must be tested by creating an account mapping linked to your configured provider, then requesting a token for the mapped account. The following procedure walks you through creating a service account and requesting a token using the client credentials flow.

1. Request an API access token from your OAuth provider’s token endpoint using the client credentials grant type.

   Most OAuth providers include testing functionality where you can get a sample token using your app registration credentials. If not, you can construct a request similar to the following and send it to the token endpoint URL.

   $
   curl --request POST "<OAUTH-PROVIDER-TOKEN-ENDPOINT>" \
   >
        --header "Content-Type: application/json" \
   >
        --data '{
   >
          "client_id": "<CLIENT-ID>",
   >
          "client_secret": "<CLIENT-SECRET>",
   >
          "audience": "<AUDIENCE>",
   >
          "grant_type": "client_credentials",
   >
        }'
   The token endpoint URL varies by provider. Common formats include:

   • Auth0 — https://<YOUR-DOMAIN>.auth0.com/oauth/token

   • Okta — https://<YOUR-DOMAIN>/oauth2/default/v1/token

   • Microsoft Entra ID — https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token (v2.0 tokens) or https://login.microsoftonline.com/<TENANT_ID>/oauth2/token (v1.0 tokens)

   Refer to your OAuth provider’s documentation for the correct endpoint.

2. Inspect the token using a JWT decoder, such as jwt.io, and extract the external account identifier passed in the subject claim (sub, unless configured otherwise).

3. Using the identifier, add an account mapping for the service account.

4. Make an API request to AI Hub using the provided token. The create batch endpoint works well for testing. Be sure to specify the name of the shared workspace you added the service account to.

   $
   curl --request POST "<API-ROOT>/v2/batches" \
   >
        --header "Authorization: Bearer <ACCESS-TOKEN>" \
   >
        --header "IB-Context: <ORGANIZATION-ID>" \
   >
        --header "Content-Type: application/json" \
   >
        --data '{
   >
          "name": "test",
   >
          "workspace": "<WORKSPACE-NAME>"
   >
        }'

If the request succeeds and returns a batch ID, your configuration is working correctly. If you encounter any issues, review all configuration settings and ensure the following:

• The audience value in AI Hub matches your OAuth provider configuration and is being passed in the aud claim.

• Claim mappings are correct if using custom claim names.

• The external account identifier in the mapping matches the subject claim in your token (typically sub).

Updating OAuth provider configurations

Select configuration changes are supported after initial setup.

1. In the header, click the initials icon and select Settings. Select the Identity & access tab.

2. In the OAuth provider configurations list, hover over the configuration, then click the overflow icon and select Edit configuration.

3. Make any changes, then click Save changes.

4. Test your updated configuration.

Disabling and deleting OAuth provider configurations

You can disable or delete your configuration. Disabling a configuration removes it as a supported authentication option for API access, but the configuration is preserved and can later be re-enabled. When re-enabled, all previously created account mappings are also restored. Deleting a configuration permanently removes it and all associated account mappings.

1. In the header, click the initials icon and select Settings. Select the Identity & access tab.

2. In the OAuth provider configurations list, hover over the configuration, then click the overflow icon and select Disable configuration or Delete configuration.

3. Click Disable or Delete to confirm.

To re-enable a configuration, click the overflow icon , then select Enable configuration.