Reference

keys

Org API keys: scoped credentials for CI and other non-interactive callers. Index · shared schemas · errors.

Procedure	Summary	REST	MCP tool	Stability
`keys.create`	Create an org API key with a subset of the caller's own scopes, optionally restricted to one project; it lasts 90 days by default and at most 90 (365 for the `ci` purpose). The secret is returned once. Trust class.	`POST`	—	experimental
`keys.list`	List an org's API keys (metadata only), newest first	`GET`	—	experimental
`keys.revoke`	Revoke an API key; it is refused from the next request on (revoked: false when already revoked)	`POST`	—	experimental

`keys.create`

Create an org API key with a subset of the caller's own scopes, optionally restricted to one project; it lasts 90 days by default and at most 90 (365 for the ci purpose). The secret is returned once. Trust class.


REST	`POST /v1/keys/create` (input as a JSON body)
RPC	`/rpc/v2/keys/create`
MCP	not a tool (returns a bearer credential); hints: none
Auth	`keys:write`; trust-class: locally only the runtime owner token; in the cloud only an interactive user session re-authenticated within 15 minutes; never an API key or an MCP token
Tenancy	`org`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{
  orgId: OrgId
  name: DisplayName
  scopes: CloudScope[]  // 1–64 items
  projectId?: ProjectId
  purpose?: Slug
  expiresInDays?: integer  // 1–365
}

Output:

TypeScript

{ key: ApiKey; secret: string }

Errors: U, NOT_FOUND, ORG_SUSPENDED, CONFLICT.

Named types: ApiKey, CloudScope, DisplayName, OrgId, ProjectId, Slug.

`keys.list`

List an org's API keys (metadata only), newest first


REST	`GET /v1/keys/list` (input as query parameters)
RPC	`/rpc/v2/keys/list`
MCP	not a tool (a cloud platform procedure; the cloud MCP surface is the curated device tools); hints: read-only, idempotent
Auth	`keys:read`
Tenancy	`org`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{ orgId: OrgId; includeRevoked?: boolean }

Output:

TypeScript

{ keys: ApiKey[] }

Errors: U, NOT_FOUND.

Named types: ApiKey, OrgId.

`keys.revoke`

Revoke an API key; it is refused from the next request on (revoked: false when already revoked)


REST	`POST /v1/keys/revoke` (input as a JSON body)
RPC	`/rpc/v2/keys/revoke`
MCP	not a tool (a cloud platform procedure; the cloud MCP surface is the curated device tools); hints: idempotent, destructive
Auth	`keys:write`
Tenancy	`org`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{ orgId: OrgId; keyId: ApiKeyId }

Output:

TypeScript

{ revoked: boolean }

Errors: U, NOT_FOUND, CONFLICT.

Named types: ApiKeyId, OrgId.