# Mint an API key POST /v1/tokens ```sh curl --request POST \ --url https://example.com/v1/tokens \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "for": { "kind": "user", "id": "example" }, "role": "admin", "capabilities": [ "example" ], "label": "example", "expiresAt": "2026-04-15T12:00:00Z", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }' ``` An API key acts for one principal (`for`: a person or a service account; default the caller), with that principal’s grants. Its `role` is a ceiling under them and its `projectId` a limit. Returns the plaintext token exactly once. A person or a service account’s key mints its own keys; only a tenant admin mints for someone else, or an `admin` key. A caller can only grant capabilities it holds, and a key limited to a project mints only keys limited to it. A key that expires mints only keys that expire no later than it, and a session opened by token sign-in mints as the key it was opened with. Only mounted when the deployment supplies a `TokenAdmin`. ## Authorizations - **[bearerAuth](https://docs.kindgi.com/v0.1.8/reference/api.md#bearerauth)** ## Parameters ### Header Parameters **Idempotency-Key** string \>= 1 characters Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per `docs/API-ROUTE-CONVENTIONS.md` §3.1). A retry sent while the first request still runs is answered `409 idempotency-key-in-flight` with `Retry-After`, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets `409 idempotency-key-replay-withheld`, with the first request’s status and when it succeeded (from 0.1.5). ## Request Body application/json A new API key. `for` is whom it acts for: the caller by default; only a tenant admin mints for someone else. object **for** Whom an API key acts for: a person, or a service account. object **kind** required string Allowed values: user service-account **id** required The user id, or the service account id. string \>= 1 characters **role** The most the key may do, under its principal’s grants: an `admin` key may administer the tenant when its principal is a tenant admin; a `member` key takes no admin action on the tenant, whoever it’s for; below it, its principal’s roles hold (a project admin’s member key administers that project). Default `member`; `admin` needs a tenant admin minting it. string Allowed values: admin member **capabilities** Framework capabilities the key carries (`env:write`, `secrets:write`, …). A caller can only grant capabilities it holds. Default none. Array\ **label** Optional human-readable label. string **expiresAt** ISO 8601 timestamp. Absent: the key never expires. When the minting key expires (or the key a token sign-in session was opened with), it’s required and no later than that key’s (`token-expiry-exceeds-minter`). string format: date-time **projectId** Limit the key to this project: a request naming another project is refused (`key-project-mismatch`). A key limited to a project mints only keys limited to it. string format: uuid ## Responses ### 201 Token minted. application/json The new key, plus its secret. object **tokenId** required string format: uuid **principal** Whom an API key acts for: a person, or a service account. object **kind** required string Allowed values: user service-account **id** required The user id, or the service account id. string \>= 1 characters **role** required The most the key may do, under its principal’s grants: an `admin` key may administer the tenant when its principal is a tenant admin; a `member` key takes no admin action on the tenant, whoever it’s for; below it, its principal’s roles hold (a project admin’s member key administers that project). string Allowed values: admin member **capabilities** required Framework capabilities the key carries (`env:write`, `secrets:write`, …). A caller can only grant capabilities it holds. Array\ **label** string **projectId** The project the key is limited to. string format: uuid **createdBy** Who minted it: `user:` or `service_account:`. string **createdAt** required string format: date-time **expiresAt** string format: date-time **revokedAt** Set once revoked; a revoked key never authenticates again. string format: date-time **lastUsedAt** When the key last authenticated a request (updated at most once a minute). string format: date-time **token** required Plaintext bearer token. Returned exactly once at mint time. string ##### Example ```json { "principal": { "kind": "user" }, "role": "admin" } ``` ### 400 Malformed request body, or the body’s `projectId` isn’t a project id (a UUID). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 401 Missing / malformed / expired / revoked bearer token. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 403 Not a tenant admin where one is needed, or a capability the caller does not hold (`permission-denied`); an `admin` key for a principal that isn’t a tenant admin (`role-exceeds-principal`); a key limited to a project minting for another (`key-project-mismatch`); a key that would outlive the key minting it, with an `expiresAt` later than that key’s or none (`token-expiry-exceeds-minter`, its `details.latestExpiresAt` the latest allowed). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 404 The body’s `projectId` names no project of this tenant (`project-not-found`), or `for` names no person or service account (`principal-not-found`). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 409 Idempotency-Key reused with a different body (`idempotency-key-body-mismatch`), or a retry of a request that succeeded: its answer carried a secret, which isn’t kept (`idempotency-key-replay-withheld`, with its `status` and `at`). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 413 The request body is over the API’s limit (`request-too-large`; `details.maxBytes` says how much). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 500 Server error (unmapped domain code or framework crash). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ## See also - [`GET /v1/tokens`: List API keys](https://docs.kindgi.com/v0.1.8/reference/api/operations/tokenslist.md) - [Error code `idempotency-key-body-mismatch`](https://docs.kindgi.com/v0.1.8/reference/errors.md#idempotency-key-body-mismatch) - [Error code `idempotency-key-replay-withheld`](https://docs.kindgi.com/v0.1.8/reference/errors.md#idempotency-key-replay-withheld) - [Error code `key-project-mismatch`](https://docs.kindgi.com/v0.1.8/reference/errors.md#key-project-mismatch) - [Error code `permission-denied`](https://docs.kindgi.com/v0.1.8/reference/errors.md#permission-denied) - [Error code `principal-not-found`](https://docs.kindgi.com/v0.1.8/reference/errors.md#principal-not-found) - [Error code `project-not-found`](https://docs.kindgi.com/v0.1.8/reference/errors.md#project-not-found) - [Error code `request-too-large`](https://docs.kindgi.com/v0.1.8/reference/errors.md#request-too-large) - [Error code `role-exceeds-principal`](https://docs.kindgi.com/v0.1.8/reference/errors.md#role-exceeds-principal) - [Error code `token-expiry-exceeds-minter`](https://docs.kindgi.com/v0.1.8/reference/errors.md#token-expiry-exceeds-minter) - [Every error code](https://docs.kindgi.com/v0.1.8/reference/errors.md)