DID Document Management
The Issuer Service creates and manages the DIDs that identify an issuer and sign its credentials. DIDs are created explicitly through the API by an administrator — they are not generated automatically on deployment. The service supports two DID methods: did:web (whose DID Documents are stored by the service and served over HTTPS) and did:key (a self-describing key-based identifier). DID Documents use Ed25519 verification keys, exposed for both authentication and assertionMethod.
All /agent endpoints require an admin Bearer token (Authorization: Bearer <token>; see Authentication).
Creating a did:web
A did:web is hosted by the service. A random UUID is appended to the supplied domain to form the identifier, a fresh Ed25519 key is generated, and the resulting DID Document is stored and served over HTTPS.
POST /agent/did/web
Request Body:
{
"domain": "issuer.example.com"
}domain: The hostname for the
did:webidentifier (e.g.issuer.example.com, optionally with a port such asissuer.example.com:8080). It must be a valid hostname.
Response Body:
{
"did": "did:web:issuer.example.com:5f1c2e88-9a3d-4f2b-8c7a-2d4e6f8a1b3c",
"didDocument": {
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/ed25519-2018/v1"
],
"id": "did:web:issuer.example.com:5f1c2e88-9a3d-4f2b-8c7a-2d4e6f8a1b3c",
"verificationMethod": [
{
"id": "did:web:issuer.example.com:5f1c2e88-9a3d-4f2b-8c7a-2d4e6f8a1b3c#key-1",
"type": "Ed25519VerificationKey2018",
"controller": "did:web:issuer.example.com:5f1c2e88-9a3d-4f2b-8c7a-2d4e6f8a1b3c",
"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
}
],
"authentication": [
"did:web:issuer.example.com:5f1c2e88-9a3d-4f2b-8c7a-2d4e6f8a1b3c#key-1"
],
"assertionMethod": [
"did:web:issuer.example.com:5f1c2e88-9a3d-4f2b-8c7a-2d4e6f8a1b3c#key-1"
]
}
}did: The created identifier, of the form
did:web:<domain>:<uuid>.didDocument: The full DID Document, including the Ed25519 verification method (
key-1) referenced by bothauthenticationandassertionMethod.
The DID Document is persisted by the service and published at a public well-known location (see Hosted did:web resolution).
Creating a did:key
A did:key encodes an Ed25519 public key directly in the identifier, so it is resolvable without hosting.
POST /agent/did/key
This endpoint takes no request body.
Response Body:
did: The created
did:keyidentifier.verificationMethodIds: Verification method identifiers that can be used for signing and assertions.
Once a DID exists, you register it as an issuer with POST /agent/issuer (body { "did": "..." }) before assigning schemas or creating credential offers. A schema and format then yield a credential configuration id such as [email protected]:sd-jwt, which credential offers reference.
Resolving and listing DIDs
GET /agent/did/:did
Resolves a DID created by the service and returns its current DID Document. URL-encode the :did value if it contains characters such as :.
Response Body:
For a DID the service does not know, the endpoint returns 200 OK with a null body rather than a 404.
GET /agent/dids
Returns the list of DIDs created by the service.
Response Body:
Hosted did:web resolution
did:web DID Documents are stored by the service and are publicly resolvable over HTTPS — no authentication is required, and these routes are exempt from rate limiting. A did:web:<domain>:<uuid> resolves to:
GET /:uuid/did.json
This is the URL a did:web resolver derives from a path-based DID such as did:web:<domain>:<uuid>. The alias GET /:uuid/.well-known/did.json serves the same document. The response is the stored DID Document JSON. Resolving a UUID that does not exist returns 404 Not Found.
Key material
Verification keys are Ed25519 (Ed25519VerificationKey2018) and are generated and held by the service's internal key-management system; private key material is never exposed through the API. The DID Documents are stored by the service; did:web documents are persisted and served over HTTPS. Each issuer DID signs credentials with the key referenced by its assertionMethod. Key rotation and service-endpoint updates on an existing DID Document are planned future capabilities.
Issuer metadata document
Each registered issuer exposes an OpenID4VCI issuer metadata document. This is issuer metadata used by wallets during issuance — it is not a domain-linkage or trust mechanism.
GET /agent/issuer/:did/.well-known/did-configuration
:did: The issuer DID (URL-encode the value if it contains characters such as
:).
The response is the issuer's OpenID4VCI metadata document, including the credential issuer identifier, the credential endpoint, and the supported credential configurations (e.g. [email protected]:sd-jwt). For a full worked example of this response body, see Issuers and Credential Configurations.
Last updated