A valid request URL is required to generate request examples{
"apiKeyId": "<string>",
"keyId": "<string>",
"name": "<string>",
"scopes": [
"devices:read"
],
"deviceIds": [
"<string>"
],
"createdBy": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"expiresAt": "2023-11-07T05:31:56Z",
"revokedAt": "2023-11-07T05:31:56Z",
"lastUsedAt": "2023-11-07T05:31:56Z",
"rotatedFrom": "<string>"
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Rename, renew or narrow a key
Updates an active key in place. Reach can only SHRINK: scopes must be a subset of what the key already holds, and deviceIds must stay inside the key’s current set (a key on the whole org can be narrowed to any devices the org owns, but there is no way back from a set to the whole org). Widening is refused, so an update can never bypass what was granted at creation; mint a new key instead.
ttlMs renews the key: the lifetime restarts from now, at most 3650 days per renewal (lifetime is time, not reach; a live key can be renewed repeatedly). A key that has already expired cannot be renewed; rotate it or create a new one. A revoked key answers 404 exactly like a missing one and cannot be edited back to life.
Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.
A valid request URL is required to generate request examples{
"apiKeyId": "<string>",
"keyId": "<string>",
"name": "<string>",
"scopes": [
"devices:read"
],
"deviceIds": [
"<string>"
],
"createdBy": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"expiresAt": "2023-11-07T05:31:56Z",
"revokedAt": "2023-11-07T05:31:56Z",
"lastUsedAt": "2023-11-07T05:31:56Z",
"rotatedFrom": "<string>"
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Authorizations
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Path Parameters
The apiKeyId from a listing, not the token and not the keyId.
Body
At least one of the fields; omitted fields keep their stored values.
A new label.
1 - 120A non empty subset of the scopes the key currently holds.
1A scope to keep.
devices:read, devices:act, devices:lease, runs:start, orders:place, apps:read, apps:write, apps:delete A non empty subset of the key's current device set (or of the org's devices, for a whole-org key).
1 - 200 elementsNew lifetime in milliseconds, measured from now. At most 3650 days per renewal.
1 <= x <= 315360000000Response
The updated key summary (never the token).
A stored key, as a listing returns it. The secret is not part of it and cannot be recovered.
The key's own id. This is what you pass to revoke it.
The public half of the token, the part before the secret.
A granted scope.
devices:read, devices:act, devices:lease, runs:start, orders:place, apps:read, apps:write, apps:delete The device subset this key may see and address, or null for the whole org.
Updated off the request path, so it can lag slightly behind the last real use.
The apiKeyId this key replaced via rotation, or null for keys minted directly.