Credentials API reference

Overview

This page lists the HTTP interfaces of IXO Credentials: the Credentials worker (offer inbox, presentation broker, block list, status-list registry, catalog) and the Auth Hub's /api/credentials routes. It does not cover the OpenID4VCI endpoints each issuer hosts or the response endpoint each verifier hosts; those follow the standards (see Issue a credential and Request proof).

The worker describes itself on every host: /openapi.json (the full contract, OpenAPI 3), /docs (an interactive reference) and /llms.txt (a short summary for agents). Where this page and /openapi.json differ, /openapi.json is right.

On the rest of this page, CREDENTIALS_WORKER_URL is one of these base URLs and HUB_URL the Auth Hub of the same network. The client library is @ixo/credentials-kit (0.1.1), with @ixo/ucan for the invocations.

Authentication

Every write, every issuer, verifier and holder read, and optionally a catalog read, carries one header:

Authorization: Bearer BASE64_CAR_UCAN_INVOCATION

The UCAN invocation must:

• be addressed to the worker's did:web (served at CREDENTIALS_WORKER_URL/.well-known/did.json; derived from the worker's configured host, never the request's Host header);
• live at most 300 seconds (60 seconds of clock skew are tolerated) and be used once;
• carry the fact { "method": "<upper-case HTTP method>", "path": "<full path, no query>" } naming the one request it is for, for example { "method": "POST", "path": "/v1/requests" };
• be signed, at every link of its proof chain, by a did:ixo or did:web (any other method, did:key included, is refused);
• stay within the token caps: at most 24 KB, 12 blocks, a delegation chain at most 4 deep, 4 proofs and 8 capabilities per UCAN, no proof used twice;
• if delegated, only attenuate: the ability is granted by its parent and the resource is identical.

With a UCAN store configured, every delegation in the chain is checked against its revocation registry (revoked: 403; registry unreachable: 503).

Whoever controls an entity's DID document can add a key to it and act as the entity on every route.

Base URL

https://dev.credentials.ixo.earth
https://test.credentials.ixo.earth
https://credentials.ixo.earth

curl -s https://dev.credentials.ixo.earth/

{"name":"IXO Credentials","version":"0.1.0","docs":"/docs","openapi":"/openapi.json","llms":"/llms.txt","health":"/health","did":"/.well-known/did.json"}

Put DIDs in paths exactly as written (for example did:web:localhost%3A34672 stays as is): path DIDs are read raw, never percent-decoded. A did:web follows the did:web method (any subdomain, a port written %3A, any path) and must be written in one canonical form: a lower-case host, no trailing dot, no percent-encoding in the host other than the %3A before a port (never %3A443), a non-ASCII host name in punycode, no IP address; in a path segment, upper-case hex only, no percent-encoded letter, digit, -, ., _ or ~, and no .well-known segment. A did:ixo is a person (did:ixo:ixo1…, lower case) or an entity (did:ixo:entity: and 32 lower-case hex digits). Any other spelling is refused with 400 in a path or body and 401 as a signer. Every timestamp in the API is unix seconds.

Endpoints

HEAD with a token is 405. Offers and requests exist only for their two parties: anyone else gets 404.

Main bodies and answers

A deposit (POST /v1/offers, POST /v1/requests) for a person who blocked the sender answers 403 blocked. Nothing is stored and no webhook is sent. A block holds for exactly the DID named: blocking did:web:a.example.com does not block did:web:b.example.com or did:web:example.com:x. The worker checks the depositor only, not the web address an offer names. One list covers issuers and verifiers. Every block, unblock and refused deposit is recorded in the worker's audit trail.

Each offer and request carries sender_key, the sender's DID in canonical form: look up the sender's name and look with it in the catalog. limit is 1 to 100 (default 50). Offer statuses: pending, accepted, declined, retracted, expired. Request statuses: pending, answered, declined, cancelled, expired.

Limits

Errors

Every non-2xx answer has one shape. Branch on error; message is a plain sentence for people; the technical cause stays in the worker's log under the same reference, which is also the X-Request-Id header. Quote the reference when you ask for support. A call without a token, for example:

curl -s https://dev.credentials.ixo.earth/v1/offers

{
  "error": "unauthenticated",
  "message": "We couldn't confirm who is calling. Sign in again and send a new request.",
  "reference": "bf3b5664-f07c-4d7b-bf41-5e655cc5fb03"
}

A deposit for a person who blocked you:

{
  "error": "blocked",
  "message": "This person is not accepting offers or requests from you.",
  "reference": "0b6f3c2e-2c1d-4f5e-9a51-6f1f3f2a9d10"
}

What to do with each class: fix the request on 400, 413 and 415; sign a fresh, request-bound invocation on 401; treat 403 blocked as final for that person; wait for Retry-After on 429 rate_limited and 503; on 429 too_many_pending, cancel or retract items you no longer need, or wait.

Webhook to the Auth Hub

The worker notifies the Hub, and only the Hub, of offer.created, offer.retracted, request.created and request.cancelled. The body carries no secret; the Hub fetches the details itself, as the person:

{ "id": "evt_6f1c0e3a9b7d4c2e8a6f0b1d3c5e7a9f", "type": "offer.created", "subject": "did:ixo:ixo1qqqsyqcyq5rqwzqfpg9scrgwpugpzysn4uq0hv", "object_id": "OFFER_ID", "created_at": 1793966400 }

object_id is the offer or request id, never the sender's ref. The header x-ixo-signature: t=UNIX_TIME,kid=WORKER_KEY_ID,sig=BASE64URL_SIGNATURE is an Ed25519 signature over UNIX_TIME.RAW_BODY with the worker's did:web key, signed afresh at every attempt. Receivers verify it with the kit's verifyWebhook, refuse a signature older than 300 seconds or more than 60 seconds in the future, and de-duplicate by id. Failed deliveries are retried at about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours, then given up; the item stays pending for the person. Deliveries can arrive out of order.

Auth Hub routes

Under HUB_URL/api/credentials, for the Hub's own pages. Authenticated with the Hub session (same origin only) or a short UCAN the person signs themselves; rate limited per person. This is a summary: the Hub's own documentation is the contract.

Every party in an answer is { did, name?, mark: { color, monogram, logo? } }, taken from the party's catalog entry, else a neutral mark. Errors are { error, message, reference, retryAfter? }:

Related guides

• IXO Credentials overview
• Hold and share credentials
• Status lists and the catalog
• Authentication matrix