SPA OAuth Clients

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 SPA OAuth Clients, which are managed in this tab.

What are SPA OAuth Clients?

SPA OAuth Client stands for Single-Page Application OAuth Client. It's a developer credential that lets you build authentication experiences using CARTO credentials (eg: Login with CARTO) in customer-facing Javascript applications. Once the end user successfully authenticates using their CARTO credentials, your application can use an OAuth Access Token.

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

Guides for developers

• You can find a step-by-step guide to create a private application using a SPA OAuth Client in the CARTO for Developers documentation.

• If CARTO is connected to a Single Sign-On identity provider, you can leverage your SSO in your end applications. Check our guide to create a private application using SSO thanks to a SPA OAuth Client

Managing your SPA OAuth Clients

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

Creating a new SPA OAuth Client

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

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

• Application Login URL: This should be the URL that your end-users will use to login in your application. For example: https://my-custom-carto-app.com/

Default SPA OAuth Client configuration. The advanced options for Callback, Logout and Origins URLs are not shown

This setup should be enough in most cases, as the Application Login URL already contains enough information to handle all authentication flows (callback, logout, origins...) — However, by unchecking the "Use default logout/callback URLs and origins" you can specify distinct sets of URLs for each OAuth flow:

• Allowed Callback URLs: After a successful login using this SPA OAuth Client, these are the list of URLs to where CARTO is allowed to redirect the user.

• Allowed Logout URLs: After a successful logout using this SPA OAuth Client. these are the list of URLs to where CARTO is allowed to redirect the user.

• Allowed Web Origins: CARTO will only accept authorization requests that use this SPA OAuth Client coming from this list of URLs.

• Allowed Origins (CORS): CARTO APIs will only accept requests (authenticated using this SPA OAuth Client) coming from this list of URLs.

Notes for using wildcard subdomains

Avoid using wildcard placeholders for subdomains in production application callbacks and allowed origins as it can make your application vulnerable to attacks.

You can use the star symbol (*) as a wildcard for subdomains, but it must be used in accordance with the following rules in order to properly function:

• The protocol of the URL must be http or https. Protocols such as com.example.app and service:jmx:rmi will not work.

• The wildcard must be located in a subdomain within the hostname component. https://*.com will not work.

• The wildcard must be located in the subdomain furthest from the root domain. https://sub.*.example.com will not work.

• The URL must not contain more than one wildcard. https://*.*.example.com will not work.

• A wildcard may be prefixed and/or suffixed with additional valid hostname characters. https://prefix-*-suffix.example.com will work.

• A URL with a valid wildcard will not match a URL more than one subdomain level in place of the wildcard. https://*.example.com will not work with https://sub1.sub2.example.com.

When you're done, click on "Save changes". You'll be back at the Credentials list.

Using your new SPA OAuth Client

To use your new SPA 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 SPA 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 SPA OAuth Client including modifying the name, URL, or advanced logout/callback/origins URLs.

If in the previous step, you choose to "Delete" your SPA 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 SPA OAuth Client, all users and services trying to use it will stop working. If this happens accidentally, just recreate the client from scratch with the same settings, and change the Client ID and Client Secret in the app's code.