Authentication

Every request to /api/robotics/v1/ carries a robot credential:

Authorization: Bearer sit_rk_<hex>

The credential is a machine principal

A robot credential is not a user account. It has no identity, no membership, and no staff permissions — it can act only on the robotics surface. This is deliberate: staff attribution (who served what, and the pay that follows from it) can never point at a robot.

Filial scoping

The credential is scoped to exactly one filial’s robotics activation, and the filial is derived from the key — you never send a filial identifier. A credential for one branch cannot see or touch another branch’s tasks, even within the same restaurant.

Scopes

Scope	Grants
serving_tasks:read	Listing and polling serving tasks.
serving_tasks:report	Claiming tasks and reporting progress.
fleet:heartbeat	Heartbeating and reading the fleet snapshot.

Credentials are issued with the scopes your integration needs; a request outside your scopes is refused.

Issuance and rotation

Keys are shown exactly once at issuance — the owner mints the credential in Sitora Biz and hands you the key; Sitora stores only a hash. The owner can rotate the credential at any time, which atomically revokes the old key and mints a new one.

Handle 401 by escalating for a new key, not by retrying: a revoked or rotated key never becomes valid again.

Standing is checked on every request

A key that authenticates is not automatically a key that may act. Every request re-checks that your certification is current, that the filial’s activation is live, and that the restaurant’s plan still includes robotics. If any of those lapse, the whole surface returns 403 with the reason named in the message — immediately, not at the next offer. A paused activation is the deliberate exception: you keep reading and heartbeating so you can park and observe the resume.

When a fleet is stood down mid-run, Sitora cancels its in-flight tasks so no order is left waiting on a robot that can no longer report.