Managing Applications

Applications in CARTO are entities that represent a custom solution developed by your organization, and they are used to manage authentication in the code of your application (read more about authentication methods), as well as managing other advanced parameters such as allowed callback URLs.

If you just want to add an external application to your CARTO Workspace as a shortcut, that can be done by an admin in the Settings. Read more about registered applications.

Applications can be created and managed in the Developers section, under the Built applications section:

Creating a new application

When you click on Create new, you'll be able to create a new application by providing the following information:

• Name: The user-facing name for the application

• Description: A short text describing what's the purpose of this application. This will be usually displayed to users below the Name.

• App URL: The URL where the application can be accessed. Unless overridden, this will also be the value of the Login URI or the Allowed Callback URLs, so your application works fine with just this URL.

• Thumbnail URL: The URL of an image (the recommended size is 150x150 pixels) that will serve as the logo for this application.

• Sharing options: Decide if you want this application to be visible for all users in the organization, for just a few groups, or just for you while you develop it. Read more in Sharing applications.

• Advanced settings: Turn this on if you want to manually set advanced settings of this application. Read more about advanced settings.

Advanced Settings

When you enable the advanced settings, a new set of inputs will be made available.

By default, when advanced settings is not enabled, the app will be a Single Page Application and will use the Login URL as the Login URL, Callback URL, and Logout URL.

• Application Type: this will define the authentication method used in the application.

  • Single Page Application: Use this type of application when developing user-facing applications that will require the end user to login using their CARTO user. Read more about authentication using Single Page Applications.

  • Machine to Machine: Use this type of application when developing backend applications to interact with the APIs programmatically, whether that's for a pure backend service, or in a user-facing application that does not use the CARTO login but still requires authentication. Read more about authentication using Machine to Machine Applications.

  • Regular Web Application: This application type will be sunset soon. Contact us for more information. The Token Endpoint Authentication Method field is only enabled for this type of application.

• Application Login URL: In some scenarios, CARTO will need your application to redirect to your application's login page. This URL needs to point to a route in your application that redirects to your App URL /authorize endpoint. It would usually take the form of https://myapp.org/login

Most times you won't need to edit any of the other optional parameters, since the Login URL will be enough information to login, authenticate and logout your application users. However, if you need to add additional URLs, here's more info on each field:

Optional URL fields

• Allowed Callback URLs: Optional. Set of URLs to which CARTO is allowed to redirect users after they authenticate. You can specify multiple valid URLs by comma-separating them. You can use the star symbol as a wildcard (*.google.com).

• Allowed Logout URLs: Optional. After a user logs out from your application you can redirect them with the returnTo query parameter. The URL that you use in returnTo must be listed here. You can specify multiple valid URLs by comma-separating them. You can use the star symbol as a wildcard placeholder for subdomains (*.google.com).

• Allowed Web Origins: Optional. List of URLs from where an authorization request can originate from. You can specify multiple valid URLs by comma-separating them. You can use the star symbol as a wildcard placeholder for subdomains (*.google.com).

• Allowed Origins (CORS): Optional. Set of URLs that will be allowed to make requests from JavaScript to the authorization endpoints (typically used with CORS). This prevents same-origin policy errors when using the app from within a web browser. By default, all your callback URLs will be allowed. You can specify multiple valid URLs by comma-separating them. You can use the star symbol as a wildcard placeholder for subdomains (*.google.com).

Using your application

Once you've created your application, you'll return to the list of built applications, where you can edit, delete and share existing applications.

To use your application, you will need to copy the Client ID and Client Secret of your application. There's a guide to building a private application that showcases how to use this feature at the CARTO for Developers documentation.

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

When you delete an application, users and services trying to use it won't be able to authenticate/login. If this happens accidentally, just recreate the app from scratch with the same settings, and change the Client ID and Client Secret in the app's code.

Sharing applications

Applications (like maps, connections, and workflows) can be shared with the following options:

• Private: only you can view and edit this app. It won't be shown to other users in the Developers or Applications tabs.

• Organization: this application will be visible to:

  • Entire organization: All users in this organization will be able to view this app. Users with the Editor role will view this app on the Developers page, and all users will view this app on the Applications page.

  • Only with specific groups: If your organization is using groups, you can select one or more groups that will be able to view this map, both in the Developers and Applications pages according to their role. The process of selecting which groups can view this app is similar to sharing maps with certain groups.

Applications are shared with the entire organization by default.

Important

• When sharing the application, you're controlling only the visibility of the application in the CARTO Workspace, not their permissions or their ability to login to the app. Use your application codebase to control the permissions and roles once the user's been authenticated.

• Only you as the owner of an application can edit the application.