A Python package for integrating CARTO maps, analysis, and data services into data science workflows.



This guide focuses on the basics of authentication in CARTOframes.

To visualize your local data with CARTOframes, you don’t need to be authenticated.

Authentication is needed to set up your credentials to save your data and visualizations to CARTO, to use Location Data Services, or the Data Observatory. Since a CARTO account is required for these cases, if you don’t already have an account, you can create one here.

Get your Master API Key

Once you have created an account, you need to get your Master API Key. The API keys page can be accessed from your CARTO Dashboard. Once there, click on your avatar to open the dashboard menu. The API keys link will be shown.

API Keys link - CARTO Dashboard

From here, copy the Master API Key to use in the next section.

Master API Key - CARTO Dashboard

Setting your credentials

The Credentials class is used to load your credentials in CARTOframes. This should be passed to every method that insteracts with your CARTO account. You can create multiple instances of credentials to manage different CARTO accounts.

There are different ways to set them but we encourage you to use the one that reads the credentials from a JSON file:

from cartoframes.auth import Credentials

creds = Credentials.from_file('creds.json')

With set_default_credentials, the same user’s authentication will be used by every CARTOframes component by default, so you don’t need to pass the parameter to every method that requires it.

from cartoframes.auth import set_default_credentials


Example creds.json file using the credentials above:

  "username": "johnsmith",
  "api_key": "b1ff3ed88761070116180189d9a1f5cb9cc80654"

Credential parameters

  • username: your CARTO account username
  • api_key: API Key of user’s CARTO account. If the data to be accessed is public, it can be set to default_public.
  • base_url: only needed for on-premise or custom installations. Typically in the form of https://username.carto.com/ for user username. On-premises installation (and others) have a different URL pattern.