API Token Management

In 🔮 Instill Core, the use of certain services requires API tokens for authentication. These tokens grant access to all organizations a user belongs to, as well as the user's own resources.

API tokens are sensitive information and should be handled with care. Do not share them with others or expose them in client-side code (e.g., in browsers or apps). For production requests, route them through your backend server, where API tokens can be securely managed via environment variables or a key management service.

#Steps to Manage API Tokens

To manage your API tokens, 🔮 Instill Core provides a secure and user-friendly interface that you can access by navigating to Console > Settings > API Tokens.

1. Access the API Tokens page:

   • Proceed to Console > Settings > API Tokens.
   • This section provides a user-friendly interface for managing all your API tokens.

2. Create a new API token:

   • Press the Create Token button.
   • Input a unique Token ID.
   • Press the Create Token button to generate the token.

3. Copy an API token:

   • Locate the token you want to copy.
   • Press the Copy button to copy the token to your clipboard.

4. Delete an API token:

   • Locate the token you want to delete.
   • Press the Delete button to delete the token.

#Secure Usage of API Tokens

#Set API Token as an Environment Variable

You can set your API token as an environment variable by using the command:

This allows you to securely reference the token from the shell using $INSTILL_API_TOKEN, avoiding the need to hardcode sensitive information directly into your scripts or code.

#Use API Tokens as Bearer Tokens

An API request should include your API token as a Bearer token in the Authorization HTTP header as follows:

#Specify an Organization for API Requests with API Tokens

API tokens are tied to individual users, not organizations.

If you belong to multiple organizations or need to specify which organization should be charged for an API request, include the Instill-Requester-Uid header to designate the organization. Credits for these requests will be applied to the specified organization. To use personal credits for an API request, simply omit the Instill-Requester-Uid header.

Or with our Python SDK, you can set the requester_id when initializing the client. Noted that with SDK, ID is used instead of UID for better experience.

Example cURL command and python snippet:

The Organization UID is a unique identifier representing the organization and can be found under Console > Your Organizations > Profile.