# API Access Tokens

All developer credentials can be created, edited, and managed in the Developers > Credentials section in CARTO Workspace. One of the most common developer credential types in CARTO are **API Access Tokens,** which are managed in this tab.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-fa32195c8e4535ce37614e101d23df298261cc2a%2FScreenshot%202024-04-29%20at%2011.34.44.png?alt=media" alt=""><figcaption></figcaption></figure>

## What are API Access Tokens?

API Access Tokens are the simplest method of authorization for a developer or an application to use the CARTO APIs. This type of token is **permanent**, meaning they are completely valid until they are deleted.

API Access Tokens can be restricted to:

* Use only specific APIs (**Allowed APIs**)
* Access only specific data sources for specific connections (**Grants**)
* Be used only by specific websites **(Referers)**

{% hint style="info" %}
API Access Tokens created by you are private and can't be modified or deleted by other users.
{% endhint %}

{% hint style="info" %}
All API Access Tokens are created using the [Tokens API](https://api-docs.carto.com/#b060994a-8dc2-4c87-8358-d3b6a7d08c5e), so tokens created in the UI are exactly the same as those created programmatically.
{% endhint %}

## Managing your API Access Tokens

After you create your first API Access Token, you will be able to view the list of existing tokens for your own user. API Access Tokens created by other users aren't shown in this list.

If you have created tokens programmatically using the Tokens API, they will also appear in this list.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-e9495c11ca3ee3486e93a658f14d459a5cf56a1b%2FScreenshot%202024-04-29%20at%2011.32.26.png?alt=media" alt=""><figcaption></figcaption></figure>

### Creating an API Access Token

If you click on "Create new" a new wizard will appear, with all the necessary fields to create a new API Access Token:

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FIdDbpbBlmMI8ZNLw3NDE%2FScreenshot%202026-04-21%20at%2010.56.07.png?alt=media&#x26;token=0d3fd1df-b505-4cec-b163-9943e849b9f0" alt=""><figcaption></figcaption></figure>

**Name**

This is a unique name you can assign to your token, so you can recognize it in contexts where other tokens are displayed such as the list of tokens in Developers. If you don't add your own name, CARTO will generate one such as "*`tk_shortid`*"

**Expiration**

Defines how long the token remains valid. After the expiration date, the token is rejected by the API and can no longer be used. Expired tokens are periodically removed.

When creating a token, you can choose a preset duration (1 day, 1 week, 1 month, 1 year) or set a custom expiration date. If no expiration date is specified, the token does not expire.

The expiration date cannot be changed after the token is created.

\
**Allowed APIs**

Your token will only be able to access the APIs that you specify here.

{% hint style="info" %}
The Import API can't be selected in combination with other APIs because it writes data (instead of reading it), and their grant structure is semantically different. We recommend creating specific tokens to use the Import API.
{% endhint %}

#### **Grants**

After you specify one or more APIs, you will have to include at least one grant for those APIs to work with. As discussed, grants are specific data sources that this token will be able to access and they are tied to specific connections. Choose a connection for your grant and you will see three types of grants:

* **Table or Tileset source**: Choose specific tables or tilesets from Data Explorer, or paste the fully qualified name if you happen to know it (eg: *`my-project.dataset.table`*).
* **SQL Query source:** Write or paste in the SQL editor the specific query that this token will be able to use. This is powerful in combination with the native data warehouse SQL parameters, as described in our API documentation.
* **Named Source:** Select or type a specific [Named Source](https://docs.carto.com/carto-user-manual/developers/named-sources) that this token should have access to. It's equivalent to a SQL query source.
* **All sources:** Choose this option if want your token to access all data available to this connection, including future tables.

{% hint style="info" %}
Not all APIs require the same type of grants. For example, Maps API accepts all types of grants, SQL API accepts "Query", "Named Source", and "All Sources", and LDS API doesn't need any grant to work.
{% endhint %}

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-1aee96f787764b6cf43f96b91348c176a40f2ae4%2FScreenshot%202024-11-22%20at%2011.16.04.png?alt=media" alt=""><figcaption><p>This token will be able to access the temperature raster table in Maps API, as well as<br>data from a query in both Maps API and SQL API</p></figcaption></figure>

#### **Token restrictions**

For security reasons, you may want your token to only be used by certain websites, especially if your token is going to be public, for example when sharing code snippets.

To do so, just specify a list of **Allowed Referers URLs**, separated by commas. All requests using this token from these URLs will be considered valid, while all the other requests will be rejected.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-d2db8e7788cc2d07f7a65fb15b715f17727e7732%2FScreenshot%202023-04-24%20at%2013.25.12.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The list of allowed referers should match the [Referer HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) sent by your application. In most cases this header will include a trailing slash so make sure to include it at the end of each URL: "<https://carto.com/".+>

Be careful when authorizing full-path referrers, for example, <https://google.com/some/path>, as, by default, most current browsers strip the path from cross-origin requests.
{% endhint %}

### Using your new token

To use your token, simply go back to the list of available tokens, hover your mouse over the token and click on **"Copy Token"**. Your token will be copied to your clipboard and you can just use it in your API calls, as described in our [API documentation](https://api-docs.carto.com).

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-0387daeb72d3b4d8c1c7d6ba71e0fd90489bf083%2FScreenshot%202024-04-29%20at%2011.36.57.png?alt=media" alt=""><figcaption></figcaption></figure>

### Editing and deleting tokens

At any point, you can edit or delete your existing tokens. If you **edit** a token you can modify any property, from adding more grants to removing allowed referers.

{% hint style="danger" %}
If you delete a token, make sure first that it's not being used in your codebase, as they will stop working as soon as they're deleted. Deleted tokens can't be recovered.
{% endhint %}

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-8b0601641caea5469a1ca1c967492b4d053644c9%2FScreenshot%202023-04-18%20at%2018.29.04.png?alt=media" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/carto-user-manual/developers/managing-credentials/api-access-tokens.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.