API Access Tokens
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
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)
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.
If you click on "Create new" a new wizard will appear, with all the necessary fields to create a new API Access Token:
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"
Your token will only be able to access the APIs that you specify here.
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.
All sources: Choose this option if want your token to access all data available to this connection, including future tables.
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.
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.
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.
All API Access Tokens are created using the , so tokens created in the UI are exactly the same as those created programmatically.
Named Source: Select or type a specific that this token should have access to. It's equivalent to a SQL query source.
The list of allowed referers should match the 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, , as, by default, most current browsers strip the path from cross-origin requests.
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 .
