API Client

link-api is Link's typed client for the account service's API, one function a route, on link-fetch. It holds no credential of its own, and it makes and checks the access tokens the service's routes take.

Its types

types is generated at every build from schemas/account.yaml and schemas/remote.yaml by build.rs, using typify. Objects are closed and string patterns are checked as an answer is read, with credentials held as Secret. Callers still enforce semantic and numeric bounds not represented by the generated Rust type. A contract change starts in the owning schema.

One function a route

Each is named as the spec's operationId, takes the route's request type and answers its answer type. ROUTES lists each method, path under base_path() (/api/v1) and function, and a test holds them to the spec's paths.

Its protocol version

The API's version is a protocol's, which src/protocol.toml declares (link_api::PROTOCOL, now 1): every call states it in its path, /api/v<current>, and a test holds the spec's server path and info.version to it. The service serves each version from oldest to current under its own path, so a change the API can't make by adding to a version advances it, with the older path kept until oldest passes it (Protocol versions).

The report's answer

The one answer read entry by entry, not closed, is the report's (Asked): an action of a kind this machine doesn't know is refused alone, so a newer service never stops an older machine's actions.

Its calls

Api is the service at one URL, cheap to clone. A call that needs a credential is handed it, a &Secret, by its caller. Api::sign_for signs an assertion with the machine signer supplied by that caller and requests an access token. The client never chooses a local credential store.

https:// only (or http:// on this machine), no redirects, an answer's size capped, and errors mapped once: a 401 is Error::SignedOut, a 429 Error::Later. What a refusal says, in the spec's words, is refused.

Machine Sign-In

Call Api::start_device with the typed enrollment request, then use Api::poll_device while the person completes approval. Read a refusal's ErrorCode through refused; AuthorizationPending is distinct from a permanent refusal. The caller owns polling, credential persistence, and what it presents to the person signing in.

Tokens and Signers

Api::sign_for signs a machine assertion and exchanges it through Api::token for the requested scope and audience. sign_for_agent binds the service principal and supplied grants instead. Api::keys fetches public verification keys, while the local JWT helpers check tokens without a network request. Keep token values in Secret, outside ordinary output.

Machine Records

Api::list_machines, grant_machine, and sign_out_machine operate on typed machine records. logout signs out the token's own machine. These methods issue the declared request with the caller's credential, and the remote endpoint validates the account and resource authority. The schema owns request fields and response shapes.

Agent Reports

Api::report_agents submits a machine's typed report and returns Asked. An empty response yields no requested actions. An action the current client does not understand is refused individually while recognized actions remain available. The caller still owns executing or refusing each returned action.

Access tokens (jwt)

Access tokens and the assertions machines sign for them, as the spec has them (MachineAssertionHeader, MachineAssertionClaims, AccessTokenHeader, AccessTokenClaims): compact JWS, Ed25519 alone.

assertion

A machine signs an assertion with its key for each access token it asks for: one request, at most ASSERTION_LIFE, 60 seconds.

check

Whatever an access token is for checks it with check and the account service's public keys alone (Keys), never asking the service. The header is read first: alg EdDSA and typ at+jwt alone, its kid one it holds. Then the signature, then the claims.

The claims

Closed: the issuer it trusts, its own audience, a subject of a kind it takes, a grant of what it's asked to do (Grants::allows), and a life no longer than its own longest, with no allowance for clocks.

Account stops

stopped::Cache merges snapshots outside requests, retaining one maximum cut per account without duplicate entries. Observed stops stay 25 hours; a caller may include historical cuts still relevant to its current authority. Older or empty responses cannot restore authority within that window. Checkers fetch every 30 seconds and retain the cache on failure. The service chooses its startup policy and persists revocations of longer-lived credentials, such as API keys.

Refreshed authority

A refreshed token may retain its original authorization in auth_time, which cannot exceed iat; stop checks and jwt::authorized_at use it instead of the token's later mint time, so refreshing cannot erase a cut.