API reference

Use https://trust-staging.rebellion.systems for development through early access, or https://trust.rebellion.systems for production. Request origin allowlisting as part of onboarding. There is no sandbox environment. Public SDK distribution is coming soon.

Send JSON with Content-Type: application/json. Examples use descriptive placeholders for IDs and signatures; generate real values with the SDK before sending them.

Choose the authorization model

A graphNodeId identifies a stable persona node. A graphKeyId identifies one device key. In edge certificates, signerGraphKeyId and subjectGraphKeyId are node IDs. In reachability queries, sourceGraphKeyId and targetGraphKeyId are also node IDs. In authorization and signed actions, graphKeyId is the signing device.

Signed reads

An authorization contains graphKeyId, nonce, signedAt and signature. Sign the UTF-8 canonical JSON of this structure using ECDSA P-256 with SHA-256, then encode the DER signature as base64:

{
  "v": "trust-graph-read-v1",
  "operation": "list-edges",
  "graphKeyId": "signing-device-id",
  "nonce": "fresh-random-nonce",
  "signedAt": "2026-11-04T12:00:00.000Z",
  "query": { "graphKeyId": "own-node-id" }
}

The query is exactly the request body without authorization. Sign before defaults, and send exactly what you signed. The signer must own the source node. Use a new nonce and timestamp for each request, including retries. The freshness window is five minutes. Prefer the SDK signing helpers over implementing canonical encoding yourself.

Signed mutations

Actions travel as {action, signature}. Sign canonical JSON of {v: "trust-graph-action-v1", ...action}. Each action names its operation, signing device, nonce, timestamp and operation-specific fields. The exact fields are listed on each resource page. Edge declarations use their own certificate signing format; use signBrowserEdgeCertificate or the corresponding signer helper.

A bound key must be usable for the operation: unrevoked, unexpired, of the right purpose and, on a node with a device chain, approved. Device authority describes the limited operations available to quarantined devices.

Errors and retries

Graph errors use {error, code?}; some conflicts include currentEdgeId. Shape errors use {error: "Invalid request", issues}. Dispatch on a documented code when present; do not assume every error has one.

After an uncertain mutation response, read the relevant state before signing another mutation. Revision-based APIs document how to distinguish success from a conflicting write. A failed attestation verification can return HTTP 200 with verified: false; HTTP success alone is not a trust result.

Rate limits

Limited graph routes return 429 with retry-after and x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset. The default general budget is 300 requests per minute per connection origin, with 120 successful writes per minute per graph key; deployments may configure those budgets. Devices, recovery and external keys also have resource-specific limits. Use the returned headers rather than assuming a deployment's budget.

Resources