Organisations

Create an organisation API key

Makes a key that belongs to the organisation and returns its full value.

POST/orgs/{org}/keys

TL;DR

Question	Answer
What does it do?	Create an organisation API key.
What does it take?	A JSON body of type `CreateOrgApiKeyBody`.
What does it return?	Status 201 with a body of type `CreatedOrgApiKey`.
What can go wrong?	`400` the body is not valid; `401` not signed in; `403` a member may not make keys (orgs.forbidden), or the request came from an origin that may not make changes; `404` no such organisation, or the caller is not a member of it; `409` the organisation already holds the most keys allowed; `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope.

What it does

Makes a key that belongs to the organisation and returns its full value. It acts only in this organisation, as its scopes allow (diagrams by default, audit:read for the audit log), and spends the owner's daily allowance. A sealed copy is kept when the server can, so the key can be revealed again; otherwise this answer is the only time it is shown. At most ten active keys.

Path parameters

Field	Type	Required	Description
`org`	`string`	yes	The organisation's id or its slug.

Request body

The body has the type CreateOrgApiKeyBody.

Field	Type	Required	Description
`name`	`string`	yes	at least 1 character; at most 60 characters; pattern `\S`.
`scopes`	`("diagrams" \| "audit:read")[]`	no	What the key may do. Left out, `["diagrams"]`. A key for a SIEM takes `["audit:read"]` alone.

Responses

Status	Meaning	Body
201	The new key, including its full value.	`CreatedOrgApiKey`
400	The body is not valid.	`ErrorResponse`
401	Not signed in.	`ErrorResponse`
403	A member may not make keys (orgs.forbidden), or the request came from an origin that may not make changes.	`ErrorResponse`
404	No such organisation, or the caller is not a member of it.	`ErrorResponse`
409	The organisation already holds the most keys allowed.	`ErrorResponse`
429	Too many requests.	`ErrorResponse`
503	Organisations are not set up on this server.	`ErrorResponse`

Response body

A 201 answer has the type CreatedOrgApiKey.

Field	Type	Required	Description
`id`	`string`	yes
`name`	`string`	yes
`prefix`	`string`	yes
`last4`	`string`	yes
`createdAt`	`integer`	yes	Milliseconds since the epoch.
`lastUsedAt`	`integer \| null`	yes	Milliseconds since the epoch, or null if never used.
`revealable`	`boolean`	yes	True when the full key can be shown again with the reveal route. False for a key made before that was possible, or on a server that cannot seal keys.
`key`	`string`	yes	The full key. When `revealable` is false this is the only time it is shown, so store it now.
`scopes`	`("diagrams" \| "audit:read")[]`	yes	`diagrams`: read the library, publish, and change its diagrams, which every key made before scopes holds. `audit:read`: read and export the audit log, and nothing else unless `diagrams` is also given.

Doc	Why
API reference	Every endpoint, and the error envelope
Schemas	Every request and response type
Tool reference	The operations as callable tools