Applications

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 Applications (SPA) and Machine-to-Machine Applications (M2M).

Single Page Application (SPA)

Single Page Applications (usually referred to as SPAs) 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 "Create new" under "Built applications"

3. Make sure to select "Single Page Application". Read more about how to create applications.

When to use SPA authentication

You should use a Single-Page application 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 Single-Page application 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)

Machine to Machine applications (usually referred to as M2M) 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 Application

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

2. Then, click on "Create new" under "Built applications"

3. Make sure to select "Machine to Machine". Read more about how to create applications.

Requesting an OAuth Access Token using your M2M Application

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 application 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 [email protected] if you’re interested in this feature.