This guide shows how you can use private datasets in your application.
In some applications you might use some public datasets but most of the applications are going to use private datasets. When working with the CARTO platform, there are two main ways of providing access to private datasets stored in your account:
Generate an API key with access (read) to those datasets.
Use OAuth for authentication.
Using API keys
This is the traditional (legacy) way of working with private datasets in the CARTO platform. You need to generate an API key in the CARTO dashboard with access (read/select) to your datasets. After you have generated the API key, you introduce this API in the initial state slice as explained in the Getting Started guide.
CARTO supports OAuth to communicate with our APIs. OAuth is the preferred way to manage credentials, so we recommend you use this protocol for implementing authentication & authorization in your applications.
scopes are used to specify what permissions will users have to give to the application. For example,
datasets:r:table_name will grant
read access to the table
The workflow is:
You login with the desired scopes.
You get an API_KEY (token) to call CARTO APIs but restricted to the requested scopes.
The first thing you need to do is go to your CARTO dashboard and create a new OAuth app as described in the documentation, in order to get the clientID for your application.
Then, you need to edit the
src/store/initialStateSlice.js file and modify the clientId property in the
oauthInitialState object. You can also modify the
scopes property to specify what permissions you want to give the application.
If you want to force authentication in your application so no unauthenticated users can access, you need to set the
forceOAuthLogin property to
true in the initialState object within the
src/store/appSlice.js file. When you activate this flag, the first screen for your application will be the following:
When your users click on the
Login with CARTO button, the OAuth protocol flow will start and your users will be asked to allow access to their CARTO account.
If you just want to restrict access to some application features, you can use the
OAuthLogin component. This will display a popup with the implicit OAuth flow.
Once the OAuth flow has been completed and the user has given consent to your application to access their CARTO account, you can get the user credentials like this:
This credentials object can be used, for instance, when using a data source from a view:
You can also use these credentials to call directly to our APIs from your models. You have an example of this in the IsochroneModel provided with the sample app template.
The credentials object contains the username and the API key, so you can use them to call any of the CARTO REST APIs endpoints.