> This page location: APIs & SDKs > CLI > Functions, storage and data > credentials
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: The Neon CLI `neon credentials` command manages branch-scoped credentials: issue a credential with storage, AI gateway, or function-invoke scopes, list the credentials on a branch, reveal a credential's secrets, rotate its secrets in place, and revoke it.

# Neon CLI command: credentials

Issue, list, reveal, rotate, and revoke scoped credentials on a branch

Last updated: 2026-11-18

The `credentials` command manages scoped credentials on a branch. A credential grants an application or agent direct access to a branch's surfaces without an account API key. Each credential carries one or more scopes and, when issued, a pair of secrets: an `api_token` and an `s3_secret_access_key`.

The available scopes are:

- `storage:read` and `storage:write` for [Neon Object Storage](https://neon.com/docs/storage/overview)
- `ai_gateway:invoke` for the [Neon AI Gateway](https://neon.com/docs/ai-gateway/overview)
- `functions:invoke` for invoking [Neon Functions](https://neon.com/docs/compute/functions/overview)

Credentials are branch-scoped. Pass `--project-id` and `--branch` to target a branch, or let the CLI resolve them from your [context file](https://neon.com/docs/cli/link). A credential's `token_id` has the form `nak_live_<hex>` and is stable across a rotation.

**Important: Store secrets when they're issued**

The `api_token` and `s3_secret_access_key` are returned only when you create or rotate a credential, or when you explicitly run `neon credentials reveal`. Store them securely as soon as they're issued.

Subcommands: [create](https://neon.com/docs/cli/credentials#create), [list](https://neon.com/docs/cli/credentials#list), [reveal](https://neon.com/docs/cli/credentials#reveal), [revoke](https://neon.com/docs/cli/credentials#revoke), [rotate](https://neon.com/docs/cli/credentials#rotate)

## neon credentials list

Lists the credentials on the branch. Secrets are never included; use [`neon credentials reveal`](https://neon.com/docs/cli/credentials#reveal) to see them.

```bash
neon credentials list [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon credentials list --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Token ID                                   Name                               Principal Type  Scopes                       Created At
nak_live_aaaa1111bbbb2222cccc3333dddd4444  Default AI gateway credential      user            ai_gateway:invoke            2026-09-10T20:02:49Z
nak_live_eeee5555ffff6666aaaa7777bbbb8888  Default object storage credential  user            storage:read, storage:write  2026-09-10T20:02:50Z
```

## neon credentials create

Issues a new credential. `--scope` is required and repeatable; pass one for each capability you want to grant. `--name` is an optional label.

```bash
neon credentials create [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--name` | Label for the credential | string | — | No |
| `--scope` | Capability to grant. Repeatable. Values: storage:read, storage:write, ai\_gateway:invoke, functions:invoke Possible values: `storage:read`, `storage:write`, `ai_gateway:invoke`, `functions:invoke` | array | — | Yes |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon credentials create --name uploads --scope storage:read --scope storage:write --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Token ID  nak_live_0123456789abcdef0123456789abcdef
Name      uploads
Scopes    storage:read, storage:write
api_token: <api_token>
s3_secret_access_key: <s3_secret_access_key>
WARNING: Store these secrets now: they are not shown again unless you run neon credentials reveal.
```

With `--output json`, the secrets stay on the object so scripts can read them:

<details>

<summary>Show output</summary>

```json
{
  "token_id": "nak_live_0123456789abcdef0123456789abcdef",
  "token_id_short": "0123456789ab",
  "name": "uploads",
  "api_token": "<api_token>",
  "s3_secret_access_key": "<s3_secret_access_key>",
  "scopes": ["storage:read", "storage:write"],
  "branch_id": "br-morning-frost-a1b2c3d4",
  "created_at": "2026-09-10T20:02:49Z"
}
```

</details>

## neon credentials reveal

Shows a credential's `api_token` and `s3_secret_access_key` again, looked up by `token_id`, together with its `branch_id`, `name`, and `scopes` from [`neon credentials list`](https://neon.com/docs/cli/credentials#list).

```bash
neon credentials reveal <tokenId> [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon credentials reveal nak_live_0123456789abcdef0123456789abcdef --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Token ID  nak_live_0123456789abcdef0123456789abcdef
Name      uploads
Scopes    storage:read, storage:write
api_token: <api_token>
s3_secret_access_key: <s3_secret_access_key>
WARNING: These are live secrets. Treat them like a password.
```

With `--output json`, `branch_id` is the branch the credential was issued on, which can be an ancestor of `--branch`. Check it before you use the secret in an environment that must stay isolated:

<details>

<summary>Show output</summary>

```json
{
  "token_id": "nak_live_0123456789abcdef0123456789abcdef",
  "token_id_short": "0123456789ab",
  "name": "uploads",
  "scopes": ["storage:read", "storage:write"],
  "branch_id": "br-morning-frost-a1b2c3d4",
  "principal_type": "user",
  "created_at": "2026-09-10T20:02:49Z",
  "api_token": "<api_token>",
  "s3_secret_access_key": "<s3_secret_access_key>"
}
```

</details>

When `--branch` does not list the credential, the command still prints its secrets, leaves out `branch_id`, `name`, and `scopes`, and prints a warning.

## neon credentials rotate

Replaces a credential's secrets in place. The `token_id` is unchanged, so anything that references the credential by ID keeps working once you update the stored secrets.

```bash
neon credentials rotate <tokenId> [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon credentials rotate nak_live_0123456789abcdef0123456789abcdef --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Token ID  nak_live_0123456789abcdef0123456789abcdef
Name      uploads
Scopes    storage:read, storage:write
api_token: <new api_token>
s3_secret_access_key: <new s3_secret_access_key>
WARNING: Store the new secrets now: a retry mints another pair and does not recover a lost response. A replica may briefly accept the previous secret.
```

## neon credentials revoke

Revokes a credential. Its secrets stop working and the `token_id` can no longer be revealed or rotated.

```bash
neon credentials revoke <tokenId> [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon credentials revoke nak_live_0123456789abcdef0123456789abcdef --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Credential nak_live_0123456789abcdef0123456789abcdef revoked
```

---

## Related docs (Functions, storage and data)

- [functions](https://neon.com/docs/cli/functions)
- [triggers](https://neon.com/docs/cli/triggers)
- [buckets](https://neon.com/docs/cli/buckets)
- [data-api](https://neon.com/docs/cli/data-api)
- [neon-auth](https://neon.com/docs/cli/neon-auth)
- [realtime](https://neon.com/docs/cli/realtime)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/cli/credentials"}` to https://feedback.neon.tech/ (no auth required).
