API authorization and identification

All AI Hub API calls require a token to authorize the request. AI Hub APIs also use a system of identification, to identify who is making the call and which account (community or commercial) a call is coming from. Identification occurs with the following values:

• User ID: Identifies the user making the request.
• Organization ID: Identifies the commercial organization of which the user is a member.
• IB-Context: A header that identifies the context of the call, that is whether the user’s community or commercial account is making the call.

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.

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.

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

IB-Context Commercial

Because AI Hub supports having both a community and a commercial account tied to the same user ID, the IB-Context header is used to define which context (account) the call is coming from. The context of the call dictates which account’s units to use when completing the call and where to store the results of the call.

To make a call with your commercial account’s context, include your organization ID as the IB-Context header value:

...
API_HEADERS = {
    'Authorization': f'Bearer {API_TOKEN}',
    'IB-Context': '<Organization_ID>'
}

To make the call with your community account’s context, you can explicitly define the context using your user ID, or omit the IB-Context header to accept the default community context:

...
API_HEADERS = {
    'Authorization': f'Bearer {API_TOKEN}',
    'IB-Context': '<User_ID>'
}

The IB-Context header is optional. By default, context is set to your community account. If you don’t explicitly define your organization ID in the IB-Context header, your community account is used to complete the call.

If your request specifies input and output directories that don’t exist in your community account and you don’t include the IB-Context header, the call fails. A call can’t complete when the specified directories don’t exist in the assumed or defined context.