Neon CLI command: credentials

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

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
ai_gateway:invoke for the Neon AI Gateway
functions:invoke for invoking Neon Functions

Credentials are branch-scoped. Pass --project-id and --branch to target a branch, or let the CLI resolve them from your context file. A credential's token_id has the form nak_live_<hex> and is stable across a rotation.

Secrets are shown only once

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, list, reveal, revoke, rotate

neon credentials list

Lists the credentials on the branch. Secrets are never included; use neon 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

title="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`	string	—	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

title="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:

Show output

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"
}

neon credentials reveal

Shows a credential's api_token and s3_secret_access_key again, looked up by token_id.

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

title="Output"

Token Id  nak_live_0123456789abcdef0123456789abcdef
api_token: <api_token>
s3_secret_access_key: <s3_secret_access_key>
WARNING: These are live secrets. Treat them like a password.

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

title="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

title="Output"

INFO: Credential nak_live_0123456789abcdef0123456789abcdef revoked