Learn everything you need to know to get started with the CARTO platform.

OAuth apps

CARTO allows you to register external applications on your CARTO account, no matter if you have an individual or organizational 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)
  • Datasets
  • 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.

Application management

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 14-day Professional plan trial 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.

OAuth apps tab in Developer settings

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.

App creation form

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.

App edition

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, showing them 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.

Connected apps

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.

OAuth flow

1. Redirect your users to the OAuth Flow

Redirect your users to this URL:

1
https://carto.com/oauth2/authorize?client_id=...

Here’s the list of parameters that you should / can provide to that GET endpoint:

Parameter Required Description
client_id Yes The unique ID of the application.
response_type Yes Must be (see section 2):
- code for the standard authorization code grant type (2.1)
- token for the OAuth 2.0 implicit flow (2.2).
state 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.
redirect_uri No The URL where users will be redirected to after they have authorised the app. If not present, the first redirect_uri from the OAuth application will be used.
scope No Space-separated list of requested permissions (see next section).

If all required parameters are correct, users will see something like this:

Example of a permission request

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_description and error_uri (more info here).

Scopes

The scope parameter will allow developers to specify what permissions will users have to give to the application.

Scope Description
(default) Without requesting any scope, you have access to /api/v4/me in order to retrieve the username, organization name and URLs for APIs endpoint.
offline Be able to use CARTO APIs without the user present, i.e: generate a refresh token (see section 4).
dataservices:geocoding
dataservices:isolines
dataservices:routing
dataservices:observatory
Access to the named data service via SQL API.
datasets:r:table_name
datasets:rw:schema.table
Access (read or read+write) to a dataset or view. Specify the schema for datasets shared by other users within the organization.
schemas:c Allows to create tables (views, sequences, etc.) on the user’s schema.
datasets:metadata 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 authorise 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:

1
https://example.com/callback?code=fd17b6af-fde8-401e-9891-a6d430f9e456

Together with the client_id and 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:

1
https://carto.com/oauth2/token

The following is the list of parameters that must be included (all of them are required):

Parameter Description
code The code generated by the OAuth server.
client_id The unique ID of the application.
client_secret The secret key of the application.
state 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.
grant_type Must be authorization_code.

Here’s an example using curl:

1
curl -d "code=VY_Qlm4Rd3WunvHZ&state=foo&client_id=3wmcayz5Dgmy&grant_type=authorization_code&client_secret=GM7IwH-srhPvM3KtUv9eztMo" -X POST https://carto.com/oauth2/token

The response should look like:

1
2
3
4
5
{
  "access_token": "GkWAiR5UpKTUUj6m_1D1eQ",
  "token_type": "bearer",
  "user_info_url": "https://something/api/v4/me"
}

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:

1
https://example.com/callback#access_token=Lhpe_LBm7GsEuDqnRNdMEw&token_type=Bearer&expires_in=3599.926442147

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 like:

  1. Create an invisible iframe with a location like: https://carto.com/oauth2/authorize?client_id=...?response_code=token&prompt=none.
  2. 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).
  3. 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 it, you just have to include an api_key parameter to the available endpoints. For example:

1
 {BASE_URL}/api/v4/me?api_key=bdda6efbfd71ae4f619018efb8883a85cdbe30fe

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. This makes it easier to support custom CARTO installations or on-premises, since you only have to hardcode one piece of data, the authorize/token endpoint URL.

4. Refresh the token

Specifying the 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 offline scope:

1
2
3
4
5
6
7
{
  "access_token": "EcUa5bebggy2QZzjf1j_yA",
  "token_type": "bearer",
  "expires_in": 3599.933042715,
  "user_info_url": "http://carto.com/api/v4/me",
  "refresh_token": "886k3JZOcZENljK6fGeJ"
}

Notice that the response now includes a refresh_token that can be used to request another (just one) token:

1
curl -d "refresh_token=886k3JZOcZENljK6fGeJ&client_id=3wmcayz5Dgmy&grant_type=refresh_token&client_secret=GM7IwH-srhPvM3KtUv9eztMo" -X POST http://carto.com/oauth2/token

Warning: The Implicit Grant doesn’t support the offline scope, hence refresh tokens are also unsupported. Redirect your users to the authorization flow again to get a new access token in this case.