For the complete documentation index, see llms.txt. This page is also available as Markdown.

did:web & Hosting

The Wallet Server creates did:web and did:key identifiers and serves the resulting did:web documents itself over HTTPS. Use did:web when you control a domain and want the DID document resolvable at a public URL; use did:key when you do not control a domain and want a self-contained identifier with no hosting.

did:web documents are stored server-side and published at a public, unauthenticated, throttle-exempt endpoint. The signing keys behind each document are Ed25519.

How the DID and its URL are built

When you create a did:web, you supply the domain that hosts it. The server generates a UUID, builds the identifier as did:web:<domain>:<uuid>, creates a fresh Ed25519 key that it embeds as the document's verification method (#key-1), and stores the resulting document keyed by that UUID.

Following the did:web specification, each : after the method maps to a / in the resolution URL. A bare-domain DID (did:web:example.com) would resolve at /.well-known/did.json, but because these DIDs carry a path segment (the UUID), resolvers fetch the document at <path>/did.json. So did:web:example.com:<uuid> resolves to:

https://example.com/<uuid>/did.json

A non-default port, if any, travels as part of the domain value (for example example.com:8080), not as a separate setting.

Configuration

The effective domain for any given DID always comes from the domain field in the create request; there is no operator-level default. The server builds the identifier directly as did:web:<domain>:<uuid> from that value, with no separate base path inserted. (See Environment & Setup for the unused DID_WEB_DOMAIN/DID_WEB_PATH variables.)

did:web requires HTTPS in production; for local development only, set ALLOW_INSECURE_HTTP=true to permit http://.

Serving the document

GET /:uuid/did.json — public, no authentication, exempt from rate limiting. This is the URL a spec-compliant did:web resolver fetches for a path-bearing DID.

The Wallet Server also serves the same document at the additional alias GET /:uuid/.well-known/did.json.

curl https://example.com/<uuid>/did.json

Response Body

The stored DID document, for example:

Requesting an unknown UUID returns 404 with the standard error body { statusCode, message, path, timestamp }.

Creating a hosted did:web

Two routes create a did:web. Both require a valid Bearer token (Authorization: Bearer <token>) with the admin role; in development you may set AUTH_DISABLED=true.

Platform identity

POST /agent/did/web creates a standalone hosted did:web (for example, to back an issuer or verifier).

Request Body

  • domain (required) — a valid hostname, optionally with a port, e.g. issuer.example.com or issuer.example.com:8080.

Response Body

  • did — the new identifier, e.g. did:web:issuer.example.com:<uuid>.

  • didDocument — the generated DID document (also now served publicly).

Per-user wallet identity

POST /agent/holder creates a per-user cloud-wallet tenant. Pass method: "web" with a domain to back the wallet with a hosted did:web; the document is served at the same public URL. Use method: "key" for a did:key wallet that needs no hosting.

Request Body

  • method (required) — "web" or "key".

  • domain — required when method is "web"; ignored for "key".

  • label (optional) — a human-readable name for the wallet.

Response Body

  • holderId — the wallet tenant id.

  • did — the wallet's DID, e.g. did:web:example.com:<uuid>.

  • cryptographicBindingMethodsSupported, credentialSigningAlgValuesSupported — the wallet's binding and signing capabilities.

  • didDocument — present for did:web holders.

did:key as the no-hosting alternative

When you do not control a domain, create a did:key instead. It carries its public key inside the identifier, so it is fully self-contained and requires no hosted document or HTTPS endpoint.

POST /agent/did/key takes no body and returns a did:key:z6Mk... identifier with its verification method ids. The same choice is available for wallets via POST /agent/holder with method: "key".

Last updated