API Access Tokens
Last updated
Last updated
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)
API Access Tokens created by you are private and can't be modified or deleted by other users.
All API Access Tokens are created using the Tokens API, so tokens created in the UI are exactly the same as those created programmatically.
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.
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.
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 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.
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.
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.
The list of allowed referers should match the Referer HTTP header 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.
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.
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.
