Skip to main content
Coming soon. Identity tokens are off by default and rolling out host by host. Until they reach your computer, the address below answers 404 with "error": "not_enabled", or the connection fails. Keep using ORGO_API_KEY until then, as described in Key scopes and computer keys.
A program on a Linux Orgo computer can ask the computer for a short-lived Orgo token. It needs no API key on disk. The token lasts one hour, reaches only that computer, and works as a Bearer token on the Orgo API.

Get a token

Run this on the computer:
The 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 answers 429 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 answer 401. 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_KEY there.
  • 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.
Orgo hands a computer at most 60 new tokens an hour, counted on each Orgo server on its own. Because the computer reuses a token for its first 20 minutes, a program never comes near that.
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.