Authentication

Gomry Cloud authenticates machines with API keys, sent as a bearer token. There is no session, no OAuth flow and no browser-facing credential — a Cloud key is a server-side secret.

Sending a key

POST /v1/scrape HTTP/1.1
Host: api.cloud.gomry.com
Authorization: Bearer gck_live_...
Content-Type: application/json

Never put a Cloud key in browser JavaScript, a mobile app, or anything else you ship to a user. The data plane sends no CORS headers, deliberately — a key that a browser can read is a key anyone can spend.

Key format

A key is the gck_live_ prefix plus 32 random bytes. There is one kind of key: it does the work and bills for it. Spend is bounded by the project’s monthly budget cap, not by the credential.

gck_test_ keys are retired. They ran the real request against the real upstream and were simply not invoiced, which made “test” a promise of a sandbox that never existed. Existing ones no longer authenticate — mint a replacement in the console.

We store only a SHA-256 hash of the key. The plaintext is returned once, at mint time, and cannot be recovered — if it is lost, revoke it and mint another. The console shows a key by its prefix and last four characters, which is enough to tell two keys apart and useless to anyone who steals the display.

Scopes

A scope names exactly one operation a key may perform, in the form service:action. A key carries the scopes you grant it and nothing else.

Field	Description
`scrape:run`	Call POST /v1/scrape — render a page and extract structured data from it.
`scrape:fetch`	Call POST /v1/fetch — render a page and return its HTML and metadata.
`toolsapi:read`	Search and inspect the tool catalogue — POST /v1/toolsapi/discover, POST /v1/toolsapi/inspect, and polling a run with GET /v1/toolsapi/runs/{runId}. Reads only; it cannot execute anything.
`toolsapi:run`	Call POST /v1/toolsapi/run — execute a tool and pay its upstream cost. This is the scope that spends: grant it separately from toolsapi:read.
`tasks:run`	Call POST /v1/superagent — start a research task. This is the scope that spends, and it commits to work that continues after the request returns.
`tasks:read`	Poll a task with GET /v1/superagent/{taskId} and stop one with DELETE. Neither is billed, so a worker that only collects results needs nothing more than this.
`inference:run`	Call POST /v1/inference — one model call, billed per input and output token at the capability you asked for. Nothing implies it: it is the only scope whose cost per call is set by how much you send rather than by the operation, so a key that may run a task must still be granted this to call the model directly.

Scopes are flat: there are no wildcards, and scrape:run does not imply scrape:fetch. They are separately priced operations, so they are separately granted — a key minted for a cheap fetch loop must not be able to spend four times the rate on extractions.

Two independent checks

A request is authorized by two separate facts, and both must hold. They fail with different codes so you can tell them apart without guessing.

Check	Failure	Fix
The key carries the scope for this operation	`403 forbidden`	Mint a key with the scope, or grant it.
The project has this API enabled	`403 api_not_enabled`	Turn the API on for the project in the console.

Keeping them separate is what stops each from silently widening the other: enabling an API must not grant new power to keys that already exist, and a broadly scoped key must not reach an API the project never turned on.

Rotation and revocation

Revocation takes effect on the next request — there is no cache of authorization decisions to wait out. To rotate without downtime, mint the new key, deploy it, then revoke the old one. A key can also be given an expiry at mint time, which is the better default for anything handed to a third party.

Overview

Guides

Billing

Sending a key

Key format

Scopes

Two independent checks

Rotation and revocation