OAuth Clients

Applications are entities that belong to your CARTO organization. They usually represent a project, and they also provide a method to authenticate that project, as well as technical configuration for that method (eg: callback url, allowed urls...). Applications are visible by the entire organization by default, but only the user that created the application can edit or delete it.

There are two types of applications: Single-Page Application (SPA OAuth Clients) and Machine-to-Machine Applications (M2M OAuth Clients).

Single Page Application (SPA OAuth Clients)

Single Page Application OAuth Clients (usually referred to as SPA OAuth Client) obtain OAuth Access Tokens for each user by presenting a login flow where the user introduces their CARTO credentials. This login flow can be the CARTO default login, or your own SSO login if it's been configured for the organization and the app.

After each user successfully logs in, the app will obtain a short-lived OAuth Access Token that you can use through your app.

How to create a Single Page Application

1. Open your CARTO Workspace and navigate to the "Developers" section

2. Then, click on "Credentials" and "Create new"

3. Make sure to select "SPA OAuth Client". Read more about how to create SPA OAuth Clients.

When to use SPA authentication

You should use a Single-Page Application OAuth Client when:

• Building a private application where the end users are also CARTO users

• Building an application where row-level security and other role-based access controls from a single table are a must for security (so that requests from your application use a different credential for each user)

We encourage and recommend the use of SPA OAuth Clients as they're easy to set up and maintain. We also recommend synchronizing your end users with CARTO using SSO to support scalable security setups.

Machine-to-Machine authentication (M2M OAuth Clients)

Machine-to-Machine OAuth Clients (usually referred to as M2M OAuth Clients) obtain OAuth Access Tokens on demand, using the client_secret of the application to request them.

It doesn't require a login flow where the user needs to type the password to get a token.

How to create a M2M OAuth Client

1. Open your CARTO Workspace and navigate to the "Developers" section

2. Then, click on "Credentials" and "Create new"

3. Make sure to select "M2M OAuth Client. Read more about how to create M2M OAuth Client.

Requesting an OAuth Access Token using your M2M OAuth Client

Here's an example of a cURL request using your application's client_secret and client_id

curl --request POST \
  --url 'https://auth.carto.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' \
  --data 'client_id={{clientID}}' \
  --data 'client_secret={{clientSecret}}' \
  --data 'audience=carto-cloud-native-api'

When to use M2M Authentication

You should use a Machine-to-Machine OAuth Client when:

• Building a private application where the end users do not exist in CARTO (and the security access levels can't be managed manually)

• You need to programmatically manage API Access Tokens and Connection

We only recommend Machine-to-Machine authentication when the use case can't be solved using the other methods.

Machine-to-Machine is only available for Enterprise Large plans and above. Please get in touch at [e-mail] if you’re interested in this feature.