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_ or puk_ 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.
Response
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.