# 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`, `lds`.                                                                                                              |
| `--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's properties.

```bash
carto credentials update token <token-id> --apis sql,maps
carto credentials update spa <client-id> --title "Updated Title"
```

## `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: 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/command-reference/credentials.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.