> For the complete documentation index, see [llms.txt](https://docs.empe.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.empe.io/develop/issuer/did-document-management.md). # 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 `; see [Authentication](/develop/issuer.md#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**: ```json { "domain": "issuer.example.com" } ``` * **domain**: The hostname for the `did:web` identifier (e.g. `issuer.example.com`, optionally with a port such as `issuer.example.com:8080`). It must be a valid hostname. **Response Body**: ```json { "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::`. * **didDocument**: The full DID Document, including the Ed25519 verification method (`key-1`) referenced by both `authentication` and `assertionMethod`. The DID Document is persisted by the service and published at a public well-known location (see [Hosted did:web resolution](#hosted-didweb-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**: ```json { "did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH", "verificationMethodIds": [ "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" ] } ``` * **did**: The created `did:key` identifier. * **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 `EmployeeBadge@1.0: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**: ```json { "did": "did:web:issuer.example.com:5f1c2e88-9a3d-4f2b-8c7a-2d4e6f8a1b3c", "didDocument": { "...": "..." } } ``` 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**: ```json [ "did:web:issuer.example.com:5f1c2e88-9a3d-4f2b-8c7a-2d4e6f8a1b3c", "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" ] ``` ## 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::` resolves to: **`GET /:uuid/did.json`** This is the URL a `did:web` resolver derives from a path-based DID such as `did:web::`. 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. `EmployeeBadge@1.0:sd-jwt`). For a full worked example of this response body, see [Issuers and Credential Configurations](/develop/issuer/issuer-and-credential-configurations.md#issuer-metadata-document). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.empe.io/develop/issuer/did-document-management.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.