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>",
"token": "<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": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Mint an API key
Creates a headless credential for your org. ANY signed-in member of the org can mint one, whatever their role: this is the product’s only headless credential, and the first step of getting started asks for it.
An API key cannot mint another key, so a leaked key cannot widen its own reach. That is a rule about the CREDENTIAL and not about the person holding it, and no role change reaches it.
A KEY NEVER CARRIES MORE SCOPE THAN YOUR OWN SESSION. Asking for one you do not hold is refused 403, not 400: the request is well formed and you are not allowed to make it. Every signed-in member holds the four device and run scopes; only an admin also holds orders:place, so a member asking for it is refused.
The key records who created it, and that is what decides who may rotate, narrow or revoke it later: you can manage the keys you created, and an admin can manage any of them.
deviceIds narrows the key to a subset of your org’s devices, and every id must already belong to your org. Narrowing applies to visibility as well as addressing, so a device outside the subset is simply not there as far as that key is concerned.
Without ttlMs the key lasts 90 days (7776000000 ms).
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>",
"token": "<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": "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.
Body
The key's name, its scopes, and optionally a device subset and a lifetime.
A label you will recognize later.
1 - 120A non empty subset of the scope vocabulary.
1A scope to grant.
devices:read, devices:act, devices:lease, runs:start, orders:place, apps:read, apps:write, apps:delete Omit for the whole org. Every id must be a device your org owns.
1 - 200 elementsLifetime in milliseconds. At most 3650 days.
1 <= x <= 315360000000Response
The key was created. This response is the ONLY time the token itself is returned.
The summary, plus the one and only time the token itself leaves the service.
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.
The full bearer token. Shown here ONCE and never stored in recoverable form.