Bind a device

Auth: Two matching one-time bind proofs.

Request and response

Angle-bracket values describe placeholders, including nested objects and numeric types; these are wire shapes, not captured service data. Replace them before sending.

POST /v1/graph-keys/bind/<bind-id>/finalize HTTP/1.1
Host: trust-staging.rebellion.systems
Content-Type: application/json

{
  "initiationProof": "<gbi-proof>",
  "completionProof": "<gbc-proof>"
}

Response shape:

{
  "status": "complete",
  "graphKey": "<completed-graph-key-object>"
}

Binding associates a P-256 public key with an AuthenSee-authenticated persona. Generate and retain the private key on the device. A bearer credential cannot replace this ceremony.

Start

POST /v1/graph-keys/bind/start

Use the SDK's recovery flow to select recoverNodeId or recoverByPersona; do not initiate an unrelated first bind to recover an account. Incompatible recovery combinations are rejected. Caller-selected provider identities and the removed deviceAdd field are rejected.

POST /v1/graph-keys/bind/start
Content-Type: application/json

{
  "publicKeyJwk": { "kty": "EC", "crv": "P-256", "x": "public-x", "y": "public-y" },
  "appOrigin": "https://your-app.example",
  "nodeKind": "human"
}

The response supplies bindId, graphKeyId, graphNodeId, hostedUrl, expiresAt and initiationProof. Persist the initiation proof, intended public key, exact origins and expiry before opening hostedUrl. The start response's node ID is provisional; the completed key supplies the authoritative node.

Complete

After the person authenticates, GET /v1/authensee/callback exchanges the provider result and returns the completion proof through the configured relay. The web return path is /trust-graph/bind/callback; bindId and completionProof arrive in its fragment. Remove the fragment promptly and match the saved bind and origins.

POST /v1/graph-keys/bind/:bindId/finalize accepts:

{
  "initiationProof": "gbi_one-time-proof-from-start",
  "completionProof": "gbc_one-time-proof-from-callback"
}

Successful completion returns {status: "complete", graphKey}. Both proofs must match the same unexpired bind. For a first bind with device-chain creation required, also supply root: {record, signature}. Use the SDK bind helpers to construct and persist that prospective root and handle supported root corrections.

GET /v1/graph-keys/bind/:bindId returns status, expiresAt and, when complete, graphKey. Status is pending, exchanged, complete, expired or failed. Polling does not reveal either proof. Match a recovered completion to the public key and node saved in the pending intent.

Recovery and errors

Fresh recovery devices on chained nodes start quarantined. Existing expired graph-purpose keys can use the ceremony to refresh their binding when the authenticated persona matches; revoked keys cannot be revived. Ordinary active-key rebinds return GRAPH_KEY_REBIND_NOT_DUE, except where the independent authentication horizon makes reauthentication eligible.

Recovery starts have a separate per-reference budget, with 429 and retry-after. Callback errors are HTML with the corresponding HTTP status, rather than the JSON format used by bind API calls.