Mint a new personal access token..
curl --request POST \ --url https://stratum.example.com/v1/iam/users/example/tokens \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "label": "example", "scopes": [ "example" ], "ttl": "example" }'Returns the freshly-minted PAT with token set to the plaintext
value. The plaintext is shown ONCE — there is no recovery path.
The DB stores only the SHA-256 hash.
scopes (optional) narrows the token’s authority to a subset of
Cedar action prefixes — compute:*, network:DescribeVPC,
* for full inheritance. An empty array (or omitted field)
means no narrowing: the token inherits the full role bindings
of the owning user.
ttl (optional) is a Go duration string (24h, 720h for
~30 days, 8760h for ~1 year). Omitted means no expiry, subject
to the install’s iam.pat_max_ttl ceiling — issuance requests
for a longer TTL are silently clamped to the ceiling.
label is operator-facing free text (“ci-runner”,
“tf-deploy-laptop”) — it doesn’t gate anything but helps the
user tell their PATs apart in the list.
Self-action: gated by iam:CreatePersonalAccessToken (every
authenticated principal can self-issue).
Admin path: iam:CreatePersonalAccessTokenAdmin.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Body
Section titled “Request Body”object
Operator-facing free text to tell PATs apart.
Cedar action prefixes narrowing the PAT’s authority.
Empty / omitted = full role-binding inheritance. Examples:
compute:*, network:DescribeVPC, *.
Token lifetime. Go duration string (24h, 720h,…).
Omitted / empty = no expiry. Clamped to the install’s
iam.pat_max_ttl ceiling.
Example generated
{ "label": "example", "scopes": [ "example" ], "ttl": "example"}Responses
Section titled “Responses”PAT minted. token carries the plaintext value — this is
the only response that ever surfaces it.
Personal Access Token. The token field is populated
ONLY on the response to POST create — every other read returns
metadata-only with token omitted.
object
The plaintext PAT value. Populated only on POST create.
Show ONCE — the DB stores only sha256(token) so this is
the only response that ever surfaces the secret. Treat
with the same care as a session cookie.
Example
{ "kind": "pat"}Bad request.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Missing or invalid token.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Headers
Section titled “Headers”Authenticated but not authorized.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}