Authenticate API requests 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 and query data, and manage settings and resources. For example, you can create new API tokens and change existing datasets 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 possible, use API tokens instead of PATs.

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, use API tokens instead of PATs because PATs have full control over your Axiom account.

For more information on how to use tokens in API requests, see Get 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 can’t 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. In Advanced permissions, choose one of the following options:

   • Select Custom and define your own permission set. This allows you to select the datasets that this token can access and the actions it can perform. In Org level permissions, you can select the actions the token can perform that affect your whole Axiom organisation. For example, creating users and changing existing notifiers.
   • Select one of the presets to auto-populate a predefined set of capabilities. For example, Preset - Evaluations allows an SDK to write evaluation traces and query comparison data.

6. Click Create.

7. Copy the API token that appears and store it securely. It won’t be displayed again.

Limit query costs of an API token

You can cap the hourly and daily query costs of an API token, in dollars. When the token exceeds a limit, its query requests fail with HTTP status code 429 until the window resets. Ingest and other operations are unaffected. This is particularly useful for tokens you give to AI agents.

To set limits when you create a token, enter an hourly limit, a daily limit, or both in Query cost limits. To add or change limits on an existing token, click Settings > API tokens, select the token, and then edit Query cost limits. The token page shows the token’s current usage against each limit.

For more information, see Set query cost limits for AI agents.

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, hold the pointer 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, use API tokens instead of PATs.

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

Determine organization ID

If you authenticate requests with a PAT, you must include the organization ID in the requests. For more information on including the organization ID in the request, see Axiom API and Axiom CLI.

Determine the organization ID in one of the following ways:

• Click Settings, and then copy the organization ID in the top right corner.
• Click Settings > General, and then find the ID section.
• Go to the Axiom app and check the URL. For example, in the URL https://app.axiom.co/axiom-abcd/datasets, the organization ID is axiom-abcd.