Neon API (unofficial showcase)
POST/projects/{project_id}/branches/{branch_id}/credentials

Create a scoped branch credential

Creates a scoped service credential for a specified project branch. Provide scopes and principal_type to define the credential's capabilities and principal. The endpoint is in beta, and returns api_token and s3_secret_access_key only once; they are not stored server-side.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 3 body fields
project_idstringrequired
The Neon project ID. Must match `^[a-z0-9-]{1,60}$`.
branch_idstringrequired
The Neon branch ID to anchor the credential to. Must match `^[a-z0-9-]{1,60}$`.

Credential settings, including its requested capabilities and principal type.

namestringoptional
Free-form customer label for the credential.
scopesarray<string>required
The capabilities to grant. Provide 1 to 16 values from: storage:read, storage:write, ai_gateway:invoke, or functions:invoke.
principal_typestringrequired
Principal type for the credential. Only `user` is customer-managed and accepted here. `function` and `system` credentials are platform-internal (e.g. function-serve auto-mint, presign signer) and are never issued through the customer-facing API.
Allowed:user

2 status codes
201Returns the issued credential, including its ID, short ID, granted scopes, branch ID, creation time, and the `api_token` and `s3_secret_access_key` secrets, which are shown only once. Includes the credential name when provided and an expiration time when one is set.
token_idstringrequired
Opaque credential id (e.g. nak_live_<32hex>).
token_id_shortstringrequired
First 12 hex chars of token_id; safe to log.
namestringoptional
Customer-supplied label, echoed back from the request. Absent when not provided.
api_tokenstringrequired
Bearer token; returned exactly once.
s3_secret_access_keystringrequired
nsk_live_<64 hex>; the AWS_SECRET_ACCESS_KEY, returned exactly once.
scopesarray<string>required
branch_idstringrequired
created_atstringrequired
expires_atstringoptional
When the credential expires; absent means never expires.
defaultReturned for a general API error. The response includes a machine-readable `code`, a human-readable `message`, and an optional `request_id` for debugging.
request_idstringoptional
Unique identifier for the request, useful for debugging. You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
codestringrequired
Machine-readable code classifying the error type. See `message` for a human-readable explanation.
Default:
messagestringrequired
Error message

Error handling

scopes and principal_type are required; scopes must contain 1 to 16 values, each from storage:read, storage:write, ai_gateway:invoke, or functions:invoke. principal_type must be user, and name must not exceed 256 characters. The project_id path parameter and branch_id path parameter must each match ^[a-z0-9-]{1,60}$.