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

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

# 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

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/[email protected] (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: [email protected]

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

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. [email protected].

# Login to multiple profiles
carto auth login                    # Auto-suggests: tenant_id/org_name/[email protected]
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/[email protected].

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

Credentials storage

See Configuration for the credentials file format, environment variables, and authentication priority.