Authorization and context identification

The AI Hub API uses a system of authorization and context identification for all API calls. Your API token authorizes the call and your user or organization ID, passed in the IB-Context header, identifies the request as coming from your community or commercial account. You can manage tokens and locate your user ID and organization ID in your user settings.

OAuth tokens

All API requests made to an AI Hub API require an OAuth access token. You can add and manage OAuth tokens yourself from the APIs settings page.

Info

For all API-based operations, authorizing by token grants the same access and permissions that the user who created the token currently has. In other words, if you’re unable to perform an operation in the UI with your current permissions, your API request for the same operation is denied.

Add a token

You can add as many tokens as needed. While you can use a single token for all AI Hub API requests, creating multiple tokens can be helpful for organizing third-party access. For example, you might use one token per third-party application, so you can selectively manage and revoke third-party access.

To add a token:

  1. In the top nav bar, click the user icon and select Settings.

  2. Select the APIs tab.

  3. Click New token.

  4. In the Label field, name your token.

  5. In the Description field, describe the token’s purpose or intended usage.

  6. (Optional) Use the Token expiry field to select or define a custom expiration date for the token. The default is No expiry.

  7. Click Add.

You can copy the token’s value by clicking the Copy icon on the token’s details card.

Refresh a token

You can refresh a token as needed. Refreshing a token updates its value.

To refresh a token:

  1. In the top nav bar, click the user icon and select Settings.

  2. Select the APIs tab.

  3. In the tokens list, locate the token to refresh.

  4. On the token’s details card, click the Refresh icon.

  5. (Optional) Select or define a custom expiration date for the refreshed token. The default is No expiry.

  6. Click Refresh token.

You can copy the token’s refreshed value by clicking the Copy icon on the token’s details card.

Delete tokens

If a token is no longer needed or you wish to revoke the access it grants, you can delete it.

To delete a specific token:

  1. In the top nav bar, click the user icon and select Settings.

  2. Select the APIs tab.

  3. In the tokens list, locate the token to delete.

  4. On the token’s details card, click the Delete (trash can) icon.

  5. In the confirmation dialog, enter the specified confirmation text.

  6. Click Delete token.

To delete all tokens:

  1. In the top nav bar, click the user icon and select Settings.

  2. Select the APIs tab.

  3. Click the three-dot icon next to New token.

  4. Select Delete all tokens.

  5. In the confirmation dialog, enter the specified confirmation text.

  6. Click Delete all tokens.

IB-Context header

Because AI Hub supports having both a community and a commercial account tied to the same user ID and API token, the IB-Context header is used in API requests to identify the context of the call. For example, commercial users have two contexts: a commercial organization account and a personal community account. The IB-Context header specifies which context (account) to use to complete the API request.

Some notes on using the IB-Context header:

  • To make a request with your community account’s context, use your user ID as the IB-Context header value.

  • To make a request with your commercial account’s context, use your organization ID as the IB-Context header value.

  • For requests that require consumption units to complete, the context dictates which account’s consumption units to use. For commercial users, this means your community account is used as the cost center if the header is undefined.

  • The context dictates where to find input files and where to save output files. If your request specifies inputs or outputs that don’t exist in the defined or default context, the request fails.

  • The IB-Context header is optional but it’s a best practice to include it in all requests, even for users without a commercial account. If the header is undefined, the default behavior is to use the community context.

User ID

Your user ID is a unique, non-editable identifier tied to your account. It’s created using the email address tied to your account.

To copy your user ID:

  1. In the top nav bar, click the user icon and select Settings.

  2. Select the APIs tab.

  3. Under User ID, click the Copy icon.

Organization ID Commercial

An organization ID is a unique, non-editable identifier tied to your commercial organization.

To copy your organization ID:

  1. In the top nav bar, click the user icon and select Settings.

  2. Select the APIs tab.

  3. Under Organization ID, click the Copy icon.