# 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.

## 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.

### Auth login options

| Option                       | Description                                                                                                 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `--env <environment>`        | Auth environment: `production`, `staging`, `local`, `dedicated-NN`. Only set this if instructed by support. |
| `--organization-name <name>` | Organization name for SSO login. Use quotes if the name contains spaces.                                    |
| `--organization-id <id>`     | Organization ID for SSO login (future support).                                                             |

## 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](/carto-for-agents/cli/examples.md#copying-maps-and-workflows-between-organizations).

## Credentials storage

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


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.