Authentication

Pydeck-carto supports two types of authentication using the carto-auth <https://github.com/cartodb/carto-auth>_ package:

• Authentication using OAuth
• Authentication using M2M file

OAuth ^^^^^

Use your CARTO account to authenticate with Python from a notebook (in local or remote), or from a Python script. This is available for any CARTO user.

.. code-block:: python

from carto_auth import CartoAuth

carto_auth = CartoAuth.from_oauth()

The carto_auth object will be used to obtain the CartoLayer credentials.

.. figure:: images/carto-auth-login.png

This method supports the following parameters:

• cache_filepath (str, optional): File path where the token is stored. Default "home()/.carto-auth/token_oauth.json".
• use_cache (bool, optional): Whether the stored cached token should be used. Default True.
• open_browser (bool, optional): Whether the web browser should be opened to authorize a user. Default True.
• api_base_url (str, optional): Base URL for a CARTO account.
• org (str, optional): Single Sign-On (SSO) organization in CARTO.

M2M (advanced) ^^^^^^^^^^^^^^

Use a file with M2M credentials to automatically login into a CARTO account. It can be uses for ETL processes .This is available for Enterprise CARTO users.

.. code-block:: python

from carto_auth import CartoAuth

carto_auth = CartoAuth.from_m2m("./carto-credentials.json")

This method supports the following parameters:

• filepath (str): File path of the CARTO credentials file.
• cache_filepath (str, optional): File path where the token is stored. Default "home()/.carto-auth/token_m2m.json".
• use_cache (bool, optional): Whether the stored cached token should be used. Default True.

CARTO credentials file

To generate CARTO Auth tokens in carto-auth you need to create a `carto_credentials.json` file with the following content:

.. code-block:: json

    {
        "api_base_url": "https://gcp-us-east1.api.carto.com",
        "client_id": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "client_secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }

To obtain the file's content, go to the Developers section in the CARTO Dashboard. More information in https://docs.carto.com/carto-user-manual/developers/carto-for-developers/#carto-for-developers.

**API Base URL**

You can directly copy the *API Base URL*. It will be different depending on the region where your account is located.

**Built applications**

Create a new "Machine to Machine" application to generate the *Client ID* and *Client Secret*.

* Click on "+ Create new".
* Fill in the name and description. The URL is irrelevant in this case, so feel free to use something like https://example.domain.com.
* Open the "Advanced Settings" menu.
* In "Application Type" select "Machine to Machine".
* Click "Save" and check that your application is listed.

From the list, copy the new *Client ID* and *Client Secret* and add them into your credentials file.