API authorization
Every call to CARTO’s APIs must be authorized, the only exception to that rule being some API calls that retrieve public user data. Once an API call has proven to be legitimate, by confirming the API key is valid, it still needs to be authorized to actually perform the requested operations on the selected resources.
Authorization is achieved by using API keys attached to the requests to be authorized.
Tip: The Authorization system works in a uniform way for any library, API, service, or tool of the CARTO platform in any of its versions.
API keys
API keys are long strings of randomly generated characters. They are attached to API requests that require authorization, like most of the requests accepted by CARTO’s APIs.
API keys can be managed from your user profile in CARTO or from the Auth API. A variety of API keys can be created, each of them defining a different set of permissions around APIs and resources. You can see below an example of a real API key as it is displayed in a CARTO account.
There is also a master API key that governs API key management and provides unrestricted access to all the APIs and resources. Below you have an example of a master API key.
API keys are sensitive. Please make sure you always transmit API keys over encrypted channels and never expose them to a different audience than the one they were designed for. Depending on the type of access grant an API key is authorized for, misuse can be dangerous and result in unauthorized access, modification, or deletion of data by a malicious user.
Warning: In particular, your master API key should be kept as secure and safe as possible. Do not use it unless absolutely necessary, and never in a client-side (JavaScript) context.
Managing your API keys
If you are already a CARTO Engine user, you can manage your API keys through the user interface after logging in to your CARTO account. If you are not, you can either sign up for a 30-day Engine trial or contact our sales team to get full access to our development platform.
API keys are managed from your user profile.
This is an example of how the authorization dashboard looks like in Builder.
Creating a new API key is straightforward. Each API key has a name and defines permissions on a set of datasets for a given API.
It is also possible to manage your API keys directly using the Auth API itself. You can read about the basics of the Auth API, or browse the Auth API Reference in order to know its endpoints.
Warning: Once an API key is generated, the set of permissions it defines cannot be changed.
Authentication
API endpoints include the name of the user account where the resource to be accessed lives. API endpoints are similar to
1
https://{user_name}.carto.com/api/...
or
1
https://{organization_name}.carto.com/user/{user_name}/api/...
So API keys refer to the CARTO account that holds the resource to be used. API keys will not identify or authenticate the user who is actually requesting access to the resource.
Currently, end user authentication and authorization needs to be performed outside CARTO, typically from the backend of the end user application. That backend will then communicate with CARTO using the appropriate API key or keys.