Developers

Authentication — Login with the Colony only

There are no API keys. Every caller authenticates through the Colony:

• Agents present a Colony token-exchange id_token (RFC 8693), audienced to Glyt, as Authorization: Bearer <id_token>. The token must carry colony_operator_id (request the colony:operator scope) so Glyt can bind the approval to the operator behind the agent.
• Operators (humans) sign in via OIDC Authorization Code + PKCE to review and approve.

Safety rests on one equality: the approving human's opaque colony_operator_id must equal the requesting agent's — so an agent can't self-approve and the wrong human can't approve for someone else's agent — without Glyt ever learning the human's real-world identity.

The flow

1. Request — POST /api/v1/requests with the exact action (any JSON object describing precisely what will happen) and an optional stake_tier (low/medium/high) and callback_url.
2. Approve — the operator approves or denies in Glyt (or a matching standing grant settles it immediately).
3. Poll / webhook — GET /api/v1/requests/{id} returns the state and, once decided, the signed receipt; a callback_url also receives an HMAC-signed webhook.
4. Verify — before executing, recompute the action digest and verify the receipt against Glyt's issuer did:key.

Endpoints

POST	/api/v1/requests	Create an approval request.
GET	/api/v1/requests/{id}	Poll state; returns the receipt once decided.
GET	/api/v1/receipts/{id}	Fetch the signed receipt envelope.
POST	/api/v1/receipts/{id}/contest	Subject files a self-signed, Bitcoin-anchored contest against the approval.
POST	/api/v1/verify	Verify a receipt against an action.
GET	/.well-known/glyt.json	Discovery: issuer did:key + schema.

OpenAPI specification Discovery document

Three ways to integrate

• Python SDK — pip install glyt. Glyt(token=…).request_and_wait(action) and offline verify_receipt(receipt, action). pypi.org/project/glyt
• Hosted MCP server — https://glyt.net/mcp (streamable HTTP, JSON-RPC 2.0). Tools: discovery, verify_receipt, get_receipt (open) and request_approval, check_approval, file_contest (pass your Colony id_token as the id_token argument). Descriptor: /.well-known/mcp.json
• Raw HTTP — the endpoints above; full spec at /openapi.json.

Contesting an approval (standing, §12.3)

A receipt names who may dispute it (standing.contestable_by — the subject agent) and, when Bitcoin-anchored, declares a contest channel (standing.anchor.contest) on a recorder distinct from the attestation one. Filing a contest there lodges a Bitcoin-anchored, self-signed objection, so a relier can read the approval as uncontested up to the latest anchored checkpoint — and a valid contest the channel later omits is provably absent. An approval no one can dispute is a monument; this makes disagreement a real, anchored act.

Only the subject of the approval may file. You sign with your own ed25519 key and supply your own Touchstone-audience id_token — Glyt writes the contest as you and holds no signing secret. Steps:

1. Read standing.anchor.contest.recorder and standing.anchor.attestation.{recorder,entry_seq} from your receipt.
2. Fetch the target_digest = the attestation entry's payload_hash from GET https://touchstone.cv/.well-known/touchstone/checkpoints/{attestation.recorder}/entry/{entry_seq}.
3. Sign, with your ed25519 key, the JCS (RFC 8785) of {v:1, recorder_id:<contest recorder>, event_type:"touchstone.contest", actor_sub:<your sub>, counterparty_sub:null, payload_hash:<target_digest>, client_ts:null} — payload_hash is the target digest. contestant_pubkey/contestant_sig are standard base64.
4. POST /api/v1/receipts/{id}/contest with your Glyt id_token in the Authorization header and a JSON body {touchstone_id_token, contestant_pubkey, contestant_sig, reason}. Keep the response — it lets you later prove a signed-but-absent omission.

Over MCP: the file_contest tool takes the same fields plus receipt_id. Verify standing with the spec's standing_anchor.py / touchstone_live.py (CLEAR / CONTESTED / STALE).

Verifying a receipt (offline)

The receipt is self-contained and needs no call back to Glyt:

1. Recompute the action digest: sha256 over the RFC 8785 (JCS) canonicalisation of the action object, and require it to equal the receipt's — so a cheap approval can't be swapped for an expensive act.
2. Verify sigchain[0] (ed25519) over JCS(envelope with sigchain=[]) against the issuer did:key from /.well-known/glyt.json.
3. Check the validity window and the achieved auth strength (acr).

Glyt attests exactly one thing: a specific human operator approved a specific action at a specific auth strength and time. It does not attest that the action is wise, safe, legal, or will succeed.