A valid request URL is required to generate request examples{
"deviceId": "<string>",
"leaseId": "<string>",
"acquiredAt": "<string>",
"expiresAt": "<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": "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
}
}Keep a device longer
Extend a lease you already hold, so work longer than one lease can keep its device. The expiry SLIDES to ten minutes from now; it does not add ten minutes to the old one, and leaseId and acquiredAt do not change, so keep using the same id.
Renew before the lease expires. An expired lease cannot be renewed, because by then the device is available to everyone else and you have to take it again.
Works on a device that is briefly unreachable, unlike acting on one: losing a claim because the phone blinked would hand it to the next caller while you are still mid task.
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{
"deviceId": "<string>",
"leaseId": "<string>",
"acquiredAt": "<string>",
"expiresAt": "<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": "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 device you hold.
Body
The lease you hold.
The id the acquire returned.
Response
The same lease, with a later expiry.
A lease you hold. The fencing token is deliberately absent: it is the token the device itself checks to shut out a stale holder, it is stamped on your calls for you, and a client has no use for it.
The device you now hold.
The lease id. Send it on every action and on the release, and treat it as a credential: it is what identifies the holder, so anyone who has it can act as you and can give the device back. This is the only response that returns it, and it is returned to the caller that just took the lease.
ISO-8601 instant the lease was granted.
ISO-8601 instant after which the lease no longer holds the device. Renew before it passes.