Get a token
Run this on the computer:Metadata-Flavor: Orgo header is required. Only GET works, over plain http on port 80. Don’t send the request through a proxy: it is refused. If your environment sets http_proxy or HTTP_PROXY, add 169.254.169.254 to no_proxy and NO_PROXY.
string
The token, starting
orgo_vm_. Send it as Authorization: Bearer <token>. Treat it as a secret: never print or log it.string
Always
Bearer.integer
Seconds until the token expires.
string
When the token expires, in UTC.
string
This computer’s UUID, the
id the REST endpoints take, such as GET /api/computers/{id}.string
The computer’s current
instance_id. It changes when the computer wakes onto a new host, so address the API with desktop_id.string
The account that owns the computer’s workspace. The token acts as that account, held to this computer.
string
The computer’s workspace UUID.
GET http://169.254.169.254/orgo/v1/identity, with the same header, answers only desktop_id, vm_id and "state": "bound". It never returns a token, and a 200 there does not mean tokens are on. The token request is the test.
Use the token
Refresh the token
Ask the address again whenever you need a token. You don’t need to store one. The computer hands back the same token while at least 40 minutes of its hour are left, and gets a new one after that, so asking before each batch of calls is cheap. A token is never written to the computer’s disk. The address allows 20 requests a second per computer, with bursts of 40. Past that it answers429 with Retry-After: 1.
After a 401, ask with ?fresh=1
The Orgo API checks on every request that the computer still stands as the token says. After a copy of the computer, a move, a transfer, or someone else joining its workspace, a token it holds can go stale and answer401. Ask once with ?fresh=1:
fresh=1 drops the token the computer kept and gets a new one. It is the only query parameter accepted. If the new token also answers 401, or the address now answers 403 or 404, the computer can no longer have a token. Stop retrying.
Errors from 169.254.169.254
Every error body is{ "error": "<code>", "message": "<one sentence>" }. A 403 not_eligible adds reason.
A program in a web page on the computer can’t get a token, and neither can a container on the computer, such as one run with Docker.
Errors from the Orgo API
The API answers a refused token with{ "error": "…", "code": "…" }, at the status in this table, on every endpoint.
What a token can call
A token acts as the computer’s own key, held to its own computer. It can call the endpoints below, about its own computer only. It can never read the computer’s passwords:GET /api/computers/{id}/vnc-password answers 403 with code: "computer_key", and GET /api/computers/{id} returns "vnc_password": null. It never manages keys or reaches your billing.
Through the Desktop API proxy and on the WebSocket paths, Orgo swaps the token for the computer’s own credential, so it never reaches the computer. A browser can’t use a token as
?token=. An open connection is checked again every 15 seconds. It can stay open past the token’s hour, and closes within about 25 seconds once the computer no longer stands as the token says.
Which computers get a token
A computer gets a token when all of these hold:- It is a Linux computer. Windows, Mac and iPhone computers get none, and some older Linux computers are not served: the connection fails. Use
ORGO_API_KEYthere. - Only its owner can use its workspace: no other member, no open invite or share link, and no workspace key, Invoicing client or MCP sign-in for it. A shared workspace gets no token for now (
403 not_eligible,reason: "workspace_shared"). - No one-computer key is bound to it.
- Its owner is a registered account that has not asked to be deleted.
Any program on the computer can ask for a token, whatever user it runs as. Treat every program there as able to act as the computer.
Related pages
- Key scopes and computer keys: the computer key a token stands in for.
- Which endpoints a one-computer key can call: the same table, for keys.
- Key expiry and rotation: how a computer key rotates until tokens arrive.