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.
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 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.
Managing your API keys
If you are already a CARTO 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 free account 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 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.
Warning: Once an API key is generated, the set of permissions it defines cannot be changed.
API endpoints include the name of the user account where the resource to be accessed lives. API endpoints are similar to
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.
CARTO allows you to register external applications on your CARTO account, regardless if you have an individual or enterprise plan.
The users of your application will be able to authenticate against their CARTO accounts by using the OAuth 2.0 protocol. You will not need to develop a custom authentication/authorization system unless you want to have more advanced features in your flow such as roles.
You will be able to ask for specific permissions to access your users data such as:
- Basic information (name, email)
- CRUD operations to tables
Below you will find information about how to create an application and allow your users to sign up and use it.
If you are already a CARTO user, you can manage your OAuth apps through the user interface after logging in to your CARTO account. If you are not, you can either sign up for a free account or contact our sales team to get full access to our development platform.
OAuth apps are managed from developer settings, under your profile settings, as well as your API Keys and Mobile apps.
Create an app
You can create a new OAuth app by clicking on the
NEW OAUTH APP button. You will have to provide a name, website URL, and at least one callback URL. Optionally, you can also add a description and a logo, which will be shown to your users when requesting access.
After that, you will see the client ID and client secret of your application, required for the authorization flow.
Edit an app
By clicking on the
EDIT button from any of the listed apps, you will be able to edit the information provided at creation.
Also, you could check the client ID and client secret of the application, required to request authorization and token. The client ID is not editable, but you can reset your client secret, which will inmediately revoke the access for all the related api keys, and generate a new one.
Remove an app
At the bottom of the edition view, there is a button to
Delete my app. This operation cannot be undone and will revoke the access from all the users and displaying a notification on their CARTO accounts. The datasets created by the app will not be deleted.
Manage connected apps
You can manage apps you have granted permission at any time from the
Connected apps section in your profile settings.
It will show a list, including name, description and icon, and access the website of each one by clicking on the name.
Also, you will be able to revoke the access of any of them to your account by clicking on the
Revoke access button. That way, the existing API keys will stop working inmediately, but the datasets created by the app will remain on your account.
1. Redirect your users to the OAuth Flow
Redirect your users to this URL:
Here’s the list of parameters that you should / can provide to that GET endpoint:
||Yes||The unique ID of the application.|
||Yes||Must be (see section 2):
||Yes||A string of your choice that will be returned to your app by the authentication server, so that you can ensure the response belongs to your request.|
||No||The URL where users will be redirected to after they have authorised the app. If not present, the first
||No||Space-separated list of requested permissions (see next section).|
If all required parameters are correct, users will see something like this:
In case there is an error, the authentication server will redirect the browser back to the provided redirect URL with additional parameters in the query string. There will always be an
error parameter, and the redirect may also include
error_uri (more info here).
The scope parameter will allow developers to specify what permissions will users have to give to the application.
|(default)||Without requesting any scope, you have access to
||Be able to use CARTO APIs without the user present, i.e: generate a refresh token (see section 4).|
||Access to the named data service via SQL API.|
||Access (read or read+write) to a dataset or view. Specify the schema for datasets shared by other users within the organization.|
||Allows to create tables (views, sequences, etc.) on the user’s schema.|
||Allows to read metadata (like name or privacy) from user tables, views and materialized views on the user’s schema.|
2. Retrieve the API key
There are two different flows to get the API key (depending on the
response_type from the previous request):
- Authorization Code Grant: used by confidential and public clients to exchange an authorization code for an access token.
- Implicit Grant: a simplified flow that can be used by public clients, where the access token is returned immediately without an extra authorization code exchange step.
2.1 Authorization Code Grant
After users login and authorize an app, CARTO redirects them to the URI specified in the
redirect_uri param, attaching a code that can be used to get a temporary API Key for that user. For example:
Together with the
client_secret, the given code can be used to retrieve the API key for the authenticated user. This code expires after 60 seconds.
App must submit a POST request to the following URL:
The following is the list of parameters that must be included (all of them are required):
||The code generated by the OAuth server. It expires after 60 seconds.|
||The unique ID of the application.|
||The secret key of the application.|
||A string of your choice that will be returned to your app by the authentication server, so that you can ensure the response belongs to your request.|
Here’s an example using curl:
The response should look like:
2.2 Implicit Grant
If you are developing a single-page application (SPA), you can use this grant type so that your app can get an access token directly, without having to make the
client_secret public. Instead of receiving a code that should then be exchanged for an access token, the browser will be redirected to the specified
redirect_uri, and include the access_token in the URL:
In order to renew the token, a SPA has to go through the OAuth flow again. Redirecting the user to the flow can be disrupting for a SPA since it can lose context when redirecting back. There are two basic strategies to do this:
A) Use state parameter or local storage
You can put any state information in the
state parameter so you keep the context when you get back to the application. Remember to always include some random token in the state for security. You can also use any normal technique (like putting the state in local storage).
B) Reauthenticate silently
There is a way to re-authenticate without redirecting the user. The trick is to use an invisible iframe in order to redirect the browser to the OAuth flow. In order to better support this, CARTO supports the
prompt=none. With this parameter, the application will get an error in case the user is not logged in or authorized, so you can handle the error and redirect the user to the flow with a redirection (so the user can interact with the consent screen). The flow would be:
- Create an invisible iframe with a location:
- Poll the location of the iframe after a while (
iframe.contentWindow.location). If you get a browser error it’s because the iframe URL is not under your domain (i.e: CARTO has not yet redirected back).
- Once you can read the iframe URL, parse it. It can either include the new token or an error. In the first case, you can start using it. In the second, you should redirect the user to the full OAuth flow (without the prompt parameter).
3. Use the given API Key to communicate with CARTO
Your app should be able to use the provided API Key to communicate with CARTO’s APIs :)
To do this, you just have to include an
api_key parameter to the available endpoints. For example:
The access token will be valid for 60 minutes. After this time, you will have to refresh it or request a new one.
Tip: The response from the token endpoint includes the full URL for the
me endpoint, so you do not have to hard-code the URLs.
4. Refresh the token
offline scope will return a
refresh_token that can be used to request a new
access_token. Here is a sample response when using the Code Authorization Grant type with the
Notice that the response now includes a
refresh_token that can be used to request another (just one) token: