M2M OAuth Clients

Machine-to-machine authentication (using M2M OAuth Clients) is only available for organizations on an Enterprise Large plan or superior. If you want to upgrade or have any questions, please contact us at [e-mail].

All developer credentials can be created, edited, and managed in the Developers > Credentials section in CARTO Workspace. One of the most common developer credential types in CARTO is M2M OAuth Clients, which are managed in this tab.

What are M2M OAuth Clients?

M2M OAuth Client stands for Machine-to-machine OAuth Client. It's a developer credential that lets you build authentication without requiring any user input. This is useful in scenarios where there's no human end user (such a backend-only application) or when integrating CARTO in existing applications that do not use CARTO credentials. Using your M2M OAuth Client, your application can request an OAuth Access Token on demand.

This OAuth Access Token has the same permissions as the owner of the M2M OAuth Client, and can be used to make any API requests as that user, such as loading maps, queries, or running workflows.

A common strategy for granular, robust authentication is to use the obtained OAuth Access Token to programmatically (server-side) generate API Access Tokens with specific data grants using the Tokens API. These API Access Tokens can then be used by the final application client-side.

Guides for developers

• You can find a step-by-step guide to integrating CARTO in your existing application using a M2M OAuth Client in the CARTO for Developers documentation.

Managing your M2M OAuth Clients

After you create your first M2M OAuth Client, you will be able to view the list of existing clients for your own user. M2M OAuth Clients created by other users aren't shown in this list.

Creating a new M2M OAuth Client

Click on "Create new > M2M OAuth Client" to get started. You'll only need to provide:

• Name: This is a purely informative name. It will be used to identify this M2M OAuth Client in other lists.

Using your new M2M OAuth Client

To use your new M2M OAuth Client in an application, you'll need both the Client ID and the Client Secret:

• Client ID: this is the unique identifier — the public key for this OAuth client. This can be copied directly from the list of credentials.

• Client Secret: this is a secret key. Anyone with access to this Client Secret and the Client ID can use this OAuth client.

Both values can be obtained after clicking the "View or edit credential" button in the contextual menu.

Once you view or edit an existing M2M OAuth Client, the Client ID and Client Secret will be available to copy. The Client Secret will be masked in the screen by default to minimize risks.

You can also make any desired changes to the M2M OAuth Client name.

If in the previous step, you choose to "Delete" your M2M OAuth Client, you'll be warned about this action and asked to confirm.

Do not share the Client ID and Client Secret of your OAuth clients and store them securely. Anyone can impersonate your application with that information.

When you delete a M2M OAuth Client, all services trying to use it will stop working. If this happens accidentally, just recreate the client from scratch, and change the Client ID and Client Secret in the app's code.