Create an API key
Mint a workspace-scoped credential. The response carries the raw token, and no later read ever shows it again.
metadata.name is required, but a key with no spec.permissions can call only scope-free endpoints, so in practice the scopes are the point of the call.
The token shows once
spec.token is in this response and in the rotate response, and nowhere else. A get or list omits it. Lose the value and rotation is the recovery path, which invalidates the old token in the same motion.
Scopes are deny by default
Each entry inspec.permissions is a resource:verb string. Resources are agents, objectives, tools, memory, api_keys, workspaces, widgets, widget_sessions, secrets, and account; verbs are read and manage, where manage implies read. "*" is the explicit full-access grant, and nothing less than that grants everything.
Two behaviors worth knowing before you script key management:
- The stored set is normalized:
objectives:manageswallowsobjectives:read, so the key you read back can list fewer scopes than you sent. secretsandaccountsupport onlymanage.
Keys are born enabled
A new key starts inSTATE_ENABLED and works immediately. state is read-only; disable and enable are the actions that move it, and a PATCH cannot.
Related
API key scopes
Rotate an API key
Update an API key
Store and use secrets
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The workspace this API key belongs to (path).
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Body
Response
OK
An API key. Every key belongs to exactly one workspace and is managed via the workspace-scoped API key routes. The only exception is the system-managed global account key, which spans all workspaces and is managed via the account global_api_key routes.
AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
Configuration for an API key.
The current lifecycle state of the API key. Output only. Keys are created STATE_ENABLED; use the :disable and :enable actions to transition between states.
STATE_UNSPECIFIED, STATE_ENABLED, STATE_DISABLED