Sign in
Project Access Tokens

Create a project access token

Changed on

Creates a project access token and returns its secret.

The secret is in this response and nowhere else. Only its hash is stored, so it cannot be retrieved, displayed, or recovered later — save it when you create it.

The name must be unique within the project, so a retry cannot mint a second credential. It cannot recover the first one either. A retry that returns 409 with code access_token_name_exists means the original create committed and its secret is unrecoverable: list the project's tokens, revoke the one holding that name, and create it again.

Requires a platform token.

post/projects/{id}/access-tokens

Request

  • Base URL: https://api.volcano.dev
  • URL: https://api.volcano.dev/projects/{id}/access-tokens
  • Auth: HTTP bearer

Path parameters

idstring uuid required

Project ID

Request body

namestring required

Held by any of the project's tokens you have not revoked, including one that has expired. Creating a duplicate returns 409 with code access_token_name_exists; revoking the holder frees the name, so a rotation can keep the name its caller already references.

scope'full' | 'read_only' required

What a project access token may do within its project.

full is everything you can do to that one project, up to and including deleting it. It cannot manage access tokens, so a leaked token cannot mint a replacement or erase the record of its own use, but for a CI or agent credential that only deploys, prefer read_only where the job allows it.

read_only refuses mutations. It is enforced by route classification rather than HTTP method, so the log and metrics query endpoints remain available even though they are POST requests that carry body filters.

read_only also refuses the reads that return a credential — service keys, anon keys, variable values, and database connection strings. Those grant write access over the project's data and keep working after the token that fetched them is revoked, so returning one to a read-only credential would make the scope a formality. An anon key is included because its permissions are chosen per key and may include uploading, deleting, and publishing.

expires_atstring date-time

Omit for a token that does not expire.

Response

Token created - save the secret now, it cannot be retrieved again

idstring uuid required
project_idstring uuid required
namestring required

Unique per project.

token_prefixstring required

First 12 characters of the secret, for recognising a token in a list.

scope'full' | 'read_only' required

What a project access token may do within its project.

full is everything you can do to that one project, up to and including deleting it. It cannot manage access tokens, so a leaked token cannot mint a replacement or erase the record of its own use, but for a CI or agent credential that only deploys, prefer read_only where the job allows it.

read_only refuses mutations. It is enforced by route classification rather than HTTP method, so the log and metrics query endpoints remain available even though they are POST requests that carry body filters.

read_only also refuses the reads that return a credential — service keys, anon keys, variable values, and database connection strings. Those grant write access over the project's data and keep working after the token that fetched them is revoked, so returning one to a read-only credential would make the scope a formality. An anon key is included because its permissions are chosen per key and may include uploading, deleting, and publishing.

status'active' | 'revoked' | 'expired' required

revoked means the token was deliberately revoked, by you or by the deletion of its project. expired means it simply reached expires_at; nothing was taken away. Both are refused, and both keep their record so a token's name, prefix, last use, and request history remain available after a leak.

A token revoked before its expiry passed stays revoked, because that is the fact worth keeping.

token_source'api' | 'cli' | 'dashboard' required

What created the token.

expires_atstring date-time nullable

Absent for a token that does not expire.

last_used_atstring date-time nullable

Updated at most once every few minutes, so it may lag slightly.

created_atstring date-time required
all_time_requestsinteger required

Requests authenticated with this token since it was created.

tokenstring required

The secret. Returned only here, and not recoverable afterwards: the server stores a hash rather than the value. Save it now.

Changes