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.
Syntax
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 my_cluster.interana.com and your API token is ABC123, you can create a new token:
curl -X POST -H "Authorization: Token ABC123" https://my_cluster.interana.com/api/create_token
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:
{"token":"XYZ789"}
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.
Example
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" https://my_cluster.interana.com/api/create_token
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"}' http://my_cluster.interana.com/api/revoke_token
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" https://my_cluster.interana.com/api/create_token
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.