> 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/command-reference/credentials.md).

# credentials

Manage application credentials — API tokens, SPA OAuth clients, and M2M OAuth clients. These credentials are separate from your personal authentication (`carto auth login`) and are used by applications and backend services to call CARTO APIs.

**Credential types:**

* **API Access Tokens** — server-side API access with specific connection and source grants.
* **SPA OAuth Clients** — Single Page Application authentication flows.
* **M2M OAuth Clients** — Machine-to-Machine authentication flows.

## `carto credentials list [type]`

List credentials, optionally filtered by type.

```bash
carto credentials list              # All credentials
carto credentials list tokens       # Only API tokens
carto credentials list spa          # Only SPA OAuth clients
carto credentials list m2m          # Only M2M OAuth clients
```

## `carto credentials create token`

Create an API Access Token. A token can be scoped to one or more `(connection, source)` pairs and an explicit list of allowed APIs.

```bash
# Single fully-qualified source
carto credentials create token \
  --connection carto_dw \
  --source "carto.shared.demo_table" \
  --apis sql,maps

# Wildcard pattern (note: minimum two dot-separated segments before the wildcard)
carto credentials create token \
  --connection carto_dw \
  --source "carto.shared.CARTO_*" \
  --apis sql,maps

# All sources on a connection, with expiry and a label
carto credentials create token \
  --connection carto_dw \
  --source "*" \
  --apis sql,maps \
  --name "demo-day-token" \
  --expiration-date 7d
```

**Options:**

| Option                  | Description                                                                                                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--connection <name>`   | Connection to grant. Repeat alongside every `--source` to grant multiple connections in one token.                                                                      |
| `--source <pattern>`    | Fully-qualified table/tileset/query, a wildcard pattern like `"carto.shared.CARTO_*"` (minimum two dot-separated segments), or `"*"` for all sources on the connection. |
| `--apis <list>`         | Comma-separated API list: `sql`, `maps`, `imports`, `exports`, `lds`. `carto export` requires the `exports` scope.                                                      |
| `--referer <url>`       | Allowed referer URL.                                                                                                                                                    |
| `--name <name>`         | Optional token label (auto-generated if omitted).                                                                                                                       |
| `--expiration-date <d>` | Optional expiry. ISO date (`2027-01-01`) or shorthand (`1d`, `2w`, `6m`, `1y`). Tokens never expire if omitted.                                                         |

## `carto credentials create spa`

Create a SPA (Single Page Application) OAuth Client.

```bash
carto credentials create spa \
  --title "My Web App" \
  --callback "https://myapp.com/callback" \
  --logout-url "https://myapp.com/logout" \
  --web-origin "https://myapp.com" \
  --allowed-origin "https://myapp.com"
```

**Options:**

| Option                   | Description                   |
| ------------------------ | ----------------------------- |
| `--title <name>`         | Application title (required). |
| `--login-uri <url>`      | Login initiation URI.         |
| `--callback <url>`       | OAuth callback URL.           |
| `--logout-url <url>`     | Logout redirect URL.          |
| `--web-origin <url>`     | Web origin URL.               |
| `--allowed-origin <url>` | Allowed CORS origin.          |

## `carto credentials create m2m`

Create a Machine-to-Machine OAuth Client.

```bash
carto credentials create m2m --title "Backend Service"
```

**Options:**

| Option           | Description                   |
| ---------------- | ----------------------------- |
| `--title <name>` | Application title (required). |

## `carto credentials get <type> <id>`

Get details for a specific credential.

```bash
carto credentials get token <token-id>
carto credentials get spa <client-id>
carto credentials get m2m <client-id>
```

## `carto credentials update <type> <id>`

Update a credential in place. For an API Access Token the token value does not change, so deployed applications keep working while you add grants or APIs.

```bash
# Add a grant on a table, or on a SQL query (commas inside the SQL are kept)
carto credentials update token <token-id> --add-grant "carto_dw,carto.shared.demo_table"
carto credentials update token <token-id> --add-grant "carto_dw,SELECT id, name FROM carto.shared.demo_table"

# The same, as separate flags
carto credentials update token <token-id> --connection carto_dw --source "carto.shared.CARTO_*"

# Allow another API, or replace the referers
carto credentials update token <token-id> --add-api maps
carto credentials update token <token-id> --referers "https://app.example.com,https://staging.example.com"

carto credentials update spa <client-id> --title "Updated Title"
```

**Options (tokens):**

| Option                | Description                                                                                                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--add-grant <pair>`  | Append a grant as `"<connection>,<source>"`. Only the first comma separates the pair, so a SQL source may contain commas. Pass `"*"` as the source to grant every source on the connection. |
| `--connection <name>` | Connection for a new grant. Use together with `--source`.                                                                                                                                   |
| `--source <pattern>`  | Source for the new grant: a table, tileset or query, a wildcard pattern, or `"*"`.                                                                                                          |
| `--add-api <api>`     | Append an allowed API: `sql`, `maps`, `imports`, `exports` or `lds`.                                                                                                                        |
| `--referers <urls>`   | Replace the allowed referers with this comma-separated list.                                                                                                                                |
| `--json-body <json>`  | Replace the whole credential body with this JSON. Read the current body first with `credentials get`.                                                                                       |

## `carto credentials delete <type> <id>`

Delete a credential. `revoke` is an alias for `delete` on M2M clients.

```bash
carto credentials delete token <token-id>
carto credentials delete spa <client-id>
carto credentials revoke m2m <client-id>
```


---

# 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 dynamically by asking a question.

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

```
GET https://docs.carto.com/carto-for-agents/cli/command-reference/credentials.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.