Credentials Management

Typical usage

The most common way to input credentials into cartoframes is through the set_default_credentials method, as below. Replace {your_user_name} with your CARTO username and {your_api_key} with your API key, which you can find at https://{your_user_name}

from cartoframes.auth import set_default_credentials


When the data we’re going to use is public, we don’t need the api_key parameter, it’s automatically set to default_public:

from cartoframes.auth import set_default_credentials


You can also set your credentials using the base_url parameter:

from cartoframes.auth import set_default_credentials


The Credentials class

Credentials management for cartoframes usage.

class cartoframes.auth.credentials.Credentials(username=None, api_key='default_public', base_url=None, session=None)

Credentials class for managing and storing user CARTO credentials. The arguments are listed in order of precedence: Credentials instances are first, key and base_url/username are taken next, and config_file (if given) is taken last. If no arguments are passed, then there will be an attempt to retrieve credentials from a previously saved session. One of the above scenarios needs to be met to successfully instantiate a Credentials object.

  • api_key (str, optional) – API key of user’s CARTO account
  • username (str, optional) – Username of CARTO account
  • base_url (str, optional) – Base URL used for API calls. This is usually of the form for user eschbacher. On premises installations (and others) have a different URL pattern.
  • session (requests.Session, optional) – requests session. See requests documentation for more information.


from cartoframes.auth import Credentials
credentials = Credentials(username='eschbacher', api_key='abcdefg')

Credentials api_key


Credentials base_url


Deletes the credentials file specified in config_file. If no file is specified, it deletes the default user credential file.

Parameters:config_file (str) – Path to configuration file. Defaults to delete the user default location if None.


To see if there is a default user credential file stored, do the following:

>>> credentials = Credentials.from_file()
>>> print(credentials)
Credentials(username='eschbacher', api_key='abcdefg',
classmethod from_credentials(credentials)

Retrives credentials from another Credentials object

classmethod from_file(config_file=None, session=None)

Retrives credentials from a file. Defaults to the user config directory


Saves current user credentials to user directory.

Parameters:config_loc (str, optional) – Location where credentials are to be stored. If no argument is provided, it will be send to the default location.


from cartoframes import Credentials
credentials = Credentials(username='eschbacher', api_key='abcdefg')  # save to default location
from cartoframes import Credentials
credentials = Credentials(username='eschbacher', api_key='abcdefg')'path/to/credentials/file')

Credentials session


Credentials username