Authenticate with tokens

This reference article explains how you can authenticate your requests to the Axiom API with tokens.

Why authenticate with tokens

You can use the Axiom API and CLI to programmatically ingest data and manage your organisation settings. For example, you can add new users and change existing monitors with API requests. To prove that these requests come from you, you must include forms of authentication called tokens in your API requests. Axiom offers two types of tokens:

• API tokens let you control the actions that can be performed with the token. For example, you can specify that requests authenticated with a certain API token can only query data from a particular dataset.
• Personal access tokens (PATs) provide full control over your Axiom account. Requests authenticated with a PAT can perform every action you can perform in Axiom.

When working with tokens, use the principle of least privilege:

• Assign only those privileges to API tokens that are necessary to perform the actions that you want.
• When possible, avoid using PATs because they have full control over your Axiom account.

For more information on how to use tokens in API requests, see Getting Started with Axiom API.

API tokens

You can use two types of API tokens in Axiom:

• Basic API tokens let you ingest data to Axiom. When you create a basic API token, you select the datasets that you allow the basic API token to access.
• Advanced API tokens let you perform a wide range of actions in Axiom beyond ingesting data. When you create an advanced API token, you select which actions you allow the advanced API token to perform. For example, you can create an advanced API token that can only query data from a particular dataset and another that has wider privileges such as creating datasets and changing existing monitors.

After creating an API token, you cannot change the privileges assigned to that API token.

Create basic API token

1. Click Settings > API tokens, and then click New API token.
2. Name your API token.
3. Optional: Give a description to the API token and set an expiration date.
4. In Token permissions, click Basic.
5. In Dataset access, select the datasets where this token can ingest data.
6. Click Create.
7. Copy the API token that appears and store it securely. It won't be displayed again.

Create advanced API token

1. Click Settings > API tokens, and then click New API token.
2. Name your API token.
3. Optional: Give a description to the API token and set an expiration date.
4. In Token permissions, click Advanced.
5. Select the datasets that this token can access and the actions it can perform.
6. In Org level permissions, select the actions the token can perform that affect your whole Axiom organisation. For example, creating users and changing existing notifiers.
7. Click Create.
8. Copy the API token that appears and store it securely. It won't be displayed again.

Regenerate API token

Similarly to passwords, it's recommended to change API tokens regularly and to set an expiration date after which the token becomes invalid. When a token expires, you can regenerate it.

To regenerate an advanced API token, follow these steps:

1. Click Settings > API tokens.
2. In the list, select the API token you want to regenerate.
3. Click Regenerate token.
4. Copy the regenerated API token that appears and store it securely. It won't be displayed again.
5. Update all the API requests where you use the API token with the regenerated token.

Delete API token

1. Click Settings > API tokens.
2. In the list, point your mouse over the API token you want to delete.
3. To the right, click Delete.

Personal access tokens (PAT)

Personal access tokens (PATs) provide full control over your Axiom account. Requests authenticated with a PAT can perform every action you can perform in Axiom. When possible, avoid using PATs.

To authenticate an API request with a PAT, include the Org ID in the requests. For more information, see Getting Started with Axiom API.

Create PAT

1. Click Settings > Profile.
2. In the Personal tokens section, click New token.
3. Name the PAT.
4. Optional: Give a description to the PAT.
5. Copy the PAT that appears and store it securely. It won't be displayed again.

Delete PAT

1. Click Settings > Profile.
2. In the list, find the PAT that you want to delete.
3. To the right of the PAT, click Delete.