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 default credentials

With set_default_credentials, the same user’s authentication will be used by every CARTOframes component. 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 set_default_credentials


Example creds.json file:

  "username": "YOUR_USERNAME",
  "api_key": "YOUR_API_KEY"

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 for user username. On-premises installation (and others) have a different URL pattern.


In this guide you learned how to authenticate to CARTO reading your credentials from a file. Check the reference to learn more about credentials and how to manage them.