> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/cli/authentication.md).

# Authentication & profiles

The CLI authenticates to CARTO with an OAuth 2.0 + PKCE browser flow. The first time you run `carto auth login`, the CLI opens your browser, you complete the standard CARTO login (including SSO if your organization requires it), and the CLI captures the resulting access token and stores it locally. For CI/CD pipelines, the CLI can also log in without a browser using [M2M credentials](#logging-in-with-m2m-credentials).

## Logging in

```bash
# Interactive browser-based login (recommended)
carto auth login

# Login to a named profile
carto auth login staging
```

The login flow:

1. Displays an authorization URL.
2. Opens your browser (you may need to copy/paste the URL manually in headless environments).
3. Waits for you to complete the login.
4. Captures the access token and your user/organization info.
5. Stores the credentials in `~/.carto_credentials.json`.
6. Configures the API base URL based on your tenant.

### Logging in to a specific organization (with or without SSO)

If your organization uses SSO, or if you have access to multiple organizations, log in with the organization name:

```bash
# Standard organization name
carto auth login --organization-name production

# Organization name with spaces (requires quotes)
carto auth login --organization-name "ACME Corporation"

# Save to a specific profile
carto auth login acme-prod --organization-name "ACME Corporation"
```

How it works:

1. The CLI queries your organization's SSO configuration from the CARTO API.
2. **If SSO is configured:** the browser opens to your organization's SSO login page (SAML/OIDC).
3. **If SSO is not configured:** standard OAuth login proceeds.
4. The organization context is preserved for re-authentication.

**Requirements:**

* Use the exact organization name (case-sensitive, include spaces in quotes).
* For SSO logins, your organization administrator must have configured SSO in CARTO.

### Logging in on a headless or remote machine

On a remote server, a container or any other machine without a browser, use `--no-launch-browser` and finish the login in two steps:

```bash
# 1. Print the login URL and exit
carto auth login --no-launch-browser

# 2. Open the URL in any browser and log in. The browser then goes to an
#    address that starts with https://carto.com/cli-callback?code=...
#    Copy that full address from the address bar.

# 3. Finish the login with that URL
carto auth login --callback "https://carto.com/cli-callback?code=..."
```

Run the `--callback` command within 10 minutes of the first one. To save the session under a named profile, pass the profile name in the `--callback` command. With `--json`, the first command returns the login URL as JSON (`action`, `url`, `next_step`), so an AI agent can hand the URL to you and finish the login afterwards.

### Logging in with M2M credentials

In CI/CD pipelines and other non-interactive environments, log in with an M2M OAuth client instead of a browser session. Create the client once with [`carto credentials create m2m`](https://docs.carto.com/carto-for-agents/cli/command-reference/credentials.md#carto-credentials-create-m2m), which prints the client ID and the client secret. Save the secret right away: the CLI shows it only once. Then pass both values to `carto auth login --m2m`, either with `--client-id` and `--client-secret` or as environment variables:

```bash
export CARTO_CLI_M2M_CLIENT_ID="your-client-id"
export CARTO_CLI_M2M_CLIENT_SECRET="your-client-secret"
export CARTO_API_BASE_URL="https://gcp-us-east1.api.carto.com"
carto auth login --m2m
```

The CLI exchanges the credentials for an access token and saves it to a profile named `m2m` (or the profile name you pass), which becomes the current profile. M2M login does not look up your tenant, so set `--api-base-url` or `CARTO_API_BASE_URL` to your organization's API base URL when it isn't the default, `https://gcp-us-east1.api.carto.com`. If the profile already holds a valid token, the CLI reuses it. Add `--force` (or `-f`) to request a new one.

### Auth login options

| Option                       | Description                                                                                                                                    |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--env <environment>`        | Auth environment. Default: `production`. Only set this if CARTO support instructs you to.                                                      |
| `--organization-name <name>` | Organization name for SSO login. Use quotes if the name contains spaces.                                                                       |
| `--no-launch-browser`        | Manual login for headless or remote machines. Prints a login URL and exits.                                                                    |
| `--callback <url>`           | Finish a `--no-launch-browser` login with the callback URL shown in your browser.                                                              |
| `--m2m`                      | Non-interactive M2M OAuth login for CI/CD.                                                                                                     |
| `--client-id <id>`           | M2M client ID. If omitted, the CLI reads `CARTO_CLI_M2M_CLIENT_ID`.                                                                            |
| `--client-secret <secret>`   | M2M client secret. If omitted, the CLI reads `CARTO_CLI_M2M_CLIENT_SECRET`.                                                                    |
| `--api-base-url <url>`       | API base URL saved in the M2M profile. If omitted, the CLI reads `CARTO_API_BASE_URL`, and falls back to `https://gcp-us-east1.api.carto.com`. |
| `--force`, `-f`              | With `--m2m`, request a new token even if the profile already holds a valid one.                                                               |

## Checking status

```bash
carto auth status                   # Status of the current profile
carto auth status production        # Status of a named profile
```

Example output:

```
$ carto auth status
✓ Authenticated

Current profile: my-org/me@example.com (default)
  Token source: credentials
  Token: eyJhbGciOiJSUzI1NiIs...
  Expiration: 23/10/2025, 12:42:45
  Time remaining: (in 18 hours)
  Status: 🟢 Valid

  Tenant: clausa.app.carto.com (gcp-us-east1)
  Organization: my-org (ac_abc123)
  User: me@example.com
```

`carto auth whoami` returns the current user's profile (user ID, name, email, account info, roles).

## Token lifetime and re-authentication

Access tokens typically expire after 24 hours. The CLI extracts the expiration from the JWT and surfaces it in `carto auth status`:

| Indicator            | Meaning                                                                |
| -------------------- | ---------------------------------------------------------------------- |
| 🟢 **Valid**         | More than 10% of token lifetime remaining.                             |
| 🟡 **Expiring soon** | Less than 10% of lifetime remaining (\~2.4 hours for a 24-hour token). |
| 🔴 **Expired**       | Token has expired and must be renewed.                                 |

When a token is expiring or expired, the CLI suggests a context-aware re-authentication command that preserves your profile, environment, and (if applicable) organization name — so you don't accidentally create a duplicate profile or end up in the wrong environment.

```
⚠️  Warning: Token is expiring soon
   Less than 10% of token lifetime remaining
   Consider re-authenticating to avoid interruptions:
   carto auth login my-profile
```

## Logging out

```bash
carto auth logout                   # Logout from the current profile
carto auth logout staging           # Logout from a named profile
```

This removes the stored credentials for that profile.

## Multiple profiles

Use **named profiles** when you work with more than one CARTO organization (production vs. staging, multiple customer accounts, multiple regions, …). Each profile holds its own credentials and tenant configuration.

A profile represents authentication to a specific:

* **Tenant** (infrastructure region) — e.g. `gcp-us-east1`, `onp-acme-prod` (self-hosted).
* **Organization** (account) — e.g. `team`, `carto-prod`.
* **User** (authenticated user) — e.g. `user@company.com`.

```bash
# Login to multiple profiles
carto auth login                    # Auto-suggests: tenant_id/org_name/user@email.com
carto auth login staging
carto auth login production

# Switch the current default profile
carto auth use production
carto auth use staging

# Use a specific profile for a single command (overrides default)
carto --profile staging maps list
carto --profile production workflows list

# List all profiles and the current default
carto auth status

# Logout removes only that profile
carto auth logout staging
```

`carto auth status` (with no arguments) shows the full hierarchy: tenant → organization → user, plus all available profiles with the current default marked.

**Profile management notes:**

* **Auto-generated names** — Login without a name suggests profiles in the format `tenant_id/org_name/user@email.com`.
* **Custom names** — Provide a short name during login (e.g., `staging`, `production`).
* **Current profile** — The default used when `--profile` is not specified.
* **Override per command** — Use `--profile <name>` on any command, or set `CARTO_PROFILE` in the environment.
* **Backwards compatibility** — Old single-profile credentials files are migrated automatically on first use.

For a detailed walkthrough of using profiles to copy maps and workflows between organizations, see [Examples → Copying maps and workflows between organizations](https://docs.carto.com/carto-for-agents/cli/examples.md#copying-maps-and-workflows-between-organizations).

## Credentials storage

See [Configuration](https://docs.carto.com/carto-for-agents/cli/configuration.md) for the credentials file format, environment variables, and authentication priority.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.carto.com/carto-for-agents/cli/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
