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/
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.
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.
Last updated