Skip to main content
You are viewing the documentation for Interana version 2. For documentation on the most recent version of Interana, go to


Scuba Docs

Generate an API token


The API uses a token based authentication model. You must have an authorization token to access the Interana Query API. Tokens must be passed in the Authorization header of each request to the API in the following format:

Authorization: Token <token>

Every user account is authorized to make requests to the API, as long as they use a valid request token.

Create an API token

Use the create_token parameter in a GET or POST request to create a token for the current user. The user must be logged in to their Interana instance, and create_token associates the API token with the currently logged in user.


You can use the following curl command:

curl -X POST -H "Authorization: Token token" https://hostname/api/create_token

For example, if your hostname is and your API token is ABC123, you can create a new token:

curl -X POST -H "Authorization: Token ABC123"

Sample success message

{"token": "XYZ789", "success": true}

Sample failure message

{"msg": "Not logged in.", "success": false}

Revoke an API token

Use the revoke_token parameter in POST request to revoke a token for the current user. You must be logged in as the associated user to revoke a token.

Pass the revoke_token parameter with the token to revoke. For example: 


For example, you can also use the following curl command to revoke a token (in this case, you are revoking token2):

curl -H "Authorization: Token token1" -H "Content-Type: application/json" -X POST -d '{"token":"token2"}' http://hostname/api/revoke_token

Rotating API tokens

You can rotate your API tokens so that they're changed frequently to minimize the effects of compromised tokens (this is also known as key rotation). The concept is that there will always be two active API tokens for the user, a primary token and a secondary token. The primary token is valid for a specified time period; for example, 1 day. On the second day, the primary token is revoked, the secondary token becomes the primary token, and a new secondary token is generated. This pattern then continues for as long as the account needs access to the API. 


In this example, on day 1 the user (or an admin logged in as a user) makes a create_token call, using their existing token (ABC123) to generate a new token:

curl -X POST "Authorization: Token ABC123"

This generates the new API token XYZ789. So on day 1, the valid API tokens are:

Primary token ABC123
Secondary token XYZ789

On day 2, the user uses the secondary token (XYZ789) to make a revoke_token call to revoke the first token (ABC123): 

curl -H "Authorization: Token XYZ789" -H "Content-Type: application/json" -X POST -d '{"token":"ABC123"}'

This revokes the first token (ABC123), which can no longer be used. 

Now the secondary token (XYZ789) becomes the primary token, which is used to make another create_token call to create a new secondary token: 

curl -X POST -H "Authorization: Token XYZ789"

This generates a new API token, DEF456.  So on day 2, the valid tokens are:

Primary token XYZ789
Secondary token DEF456

On day 3, the user (or an admin logged in as that user) repeats the process, using the current secondary token (DEF456) to revoke the current primary token (XYZ789), and then to generate a new API token. Subsequent days follow the same process.