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.jsonA 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.jsonResponse 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.comorissuer.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 whenmethodis"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 fordid:webholders.
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