Skip to content
Plune Plune Plune Docs

Change what a token may do

PATCH
/v1/tokens/{id}
 
curl --request PATCH \
  --url https://beta-api.plune.ai/v1/tokens/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Content-Type: application/json' \
  --cookie plune_session=<plune_session> \
  --data '{ "scope": "write" }'

Account → API tokens (api.ts → setTokenScope), #1283. {"scope": "read" | "write"}: the next request that carries the token is judged by the new scope, and the token is not reissued - the secret in a CI job stays the same. A change writes an api_token entry (before and after) to the audit log of the token’s project; saying the scope it already has writes none. Session-only on purpose: a token must not be able to widen itself.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

Request Body required

Section titled “Request Body required ”
Media type application/json
object
scope
required

What a token may do (#1283). read answers GET, HEAD and OPTIONS (and POST /v1/test-cases/resolve, which only reads) and refuses every other request with 403 read-only token, each refusal written to the audit log as an api_token entry of action event (the token, the method and the path). write is everything its owner may do, and is what every token issued before this existed holds. Whatever its scope, a token that names a session in X-Plune-Session (an agent) is refused every DELETE with 403 agent_cannot_delete (#1280): a deletion is confirmed by a person. A token without the header, and a person with a session cookie, are not held.

string
Allowed values: read write
Example 
{
  "scope": "write"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The token as the list shows it

Media type application/json
object
id
required
string format: uuid
scope
required

What a token may do (#1283). read answers GET, HEAD and OPTIONS (and POST /v1/test-cases/resolve, which only reads) and refuses every other request with 403 read-only token, each refusal written to the audit log as an api_token entry of action event (the token, the method and the path). write is everything its owner may do, and is what every token issued before this existed holds. Whatever its scope, a token that names a session in X-Plune-Session (an agent) is refused every DELETE with 403 agent_cannot_delete (#1280): a deletion is confirmed by a person. A token without the header, and a person with a session cookie, are not held.

string
Allowed values: read write
prefix
required
string
createdAt
required
string format: date-time
revokedAt
required
string format: date-time
nullable
expiresAt

When the token stops working on its own. null for tokens issued before expiry existed (#258); new ones get 90 days.

string format: date-time
nullable
projectId
required

The project it writes to. null — every token from before B8-team — means the owner’s default project.

string
nullable
Example 
{
  "scope": "read"
}

400

Section titled “400 ”

A scope that is neither read nor write

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

401

Section titled “401 ”

No / invalid session

404

Section titled “404 ”

Not your token, or no longer live (existence is never revealed)

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

429

Section titled “429 ”

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the window rolls over