DID Management
A Decentralized Identifier (DID) gives a wallet a portable, verifiable identity that credentials can be bound to. This page covers creating a DID from a wallet key, importing an existing DID, and listing or deleting DIDs.
A wallet needs a DID store to manage DIDs — the default wallet setup includes one (see Managing Wallets).
Local Development: the API is available at http://localhost:7006 by default, whether Wallet API v2 runs standalone or via the Docker Compose quick start.
Default DID
Receiving and presenting credential endpoints accept an optional did. When you omit it, the wallet uses its default DID. By default, that is the first DID in the wallet's DID store, then the staticDid for a store-less wallet. You can override it with Set the Default DID, or pass did explicitly on each call.
Create a DID
Create a DID from a key in the wallet. If you omit keyId, the wallet's default key is used.
Pass method-specific registrar arguments in options when the DID method needs them — for example domain and path for did:web.
Endpoint: POST /wallet/{walletId}/dids/create | API Reference
Example Request — did:key
curl -X POST http://localhost:7006/wallet/{walletId}/dids/create \
-H 'Content-Type: application/json' \
-d '{ "method": "key" }'
Example Request — did:web
curl -X POST http://localhost:7006/wallet/{walletId}/dids/create \
-H 'Content-Type: application/json' \
-d '{
"method": "web",
"options": {
"domain": "example.com",
"path": "/users/alice"
}
}'
Path Parameters
- walletId: String (required) - The wallet to create the DID in. See Managing Wallets.
Body Parameters
- method: String (required) - The DID method to create. Supported:
key,jwk,web,cheqd. - keyId: String (optional) - The key to derive the DID from. Defaults to the wallet's default key.
- options: Object (optional) - Method-specific registrar arguments. Common keys:
- did:web —
domain(required),path(optional, e.g./users/alice) - did:key —
useJwkJcsPub(optional boolean, e.g. for EBSI)
- did:web —
Example Response — did:key
{
"did": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6",
"document": {
"@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/jws-2020/v1"],
"id": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6",
"verificationMethod": [
{
"id": "did:key:z6Mkfri...#z6Mkfri...",
"type": "JsonWebKey2020",
"controller": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6",
"publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "..." }
}
],
"assertionMethod": ["did:key:z6Mkfri...#z6Mkfri..."],
"authentication": ["did:key:z6Mkfri...#z6Mkfri..."]
}
}
Example Response — did:web
{
"did": "did:web:example.com:users:alice",
"document": {
"@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/jws-2020/v1"],
"id": "did:web:example.com:users:alice",
"verificationMethod": [
{
"id": "did:web:example.com:users:alice#...",
"type": "JsonWebKey2020",
"controller": "did:web:example.com:users:alice",
"publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "..." }
}
],
"assertionMethod": ["did:web:example.com:users:alice#..."],
"authentication": ["did:web:example.com:users:alice#..."]
}
}
Response Fields
- did: String - The newly created DID.
- document: Object - The DID document. For
did:web, host this document at the configured domain and path so the DID is publicly resolvable (Wallet API v2 stores it in the wallet but does not host it for you).
Already have a DID registered elsewhere? Bring it into the wallet with Import a DID.
Import a DID
Import an existing DID and its document.
Endpoint: POST /wallet/{walletId}/dids/import | API Reference
Example Request
curl -X POST http://localhost:7006/wallet/{walletId}/dids/import \
-H 'Content-Type: application/json' \
-d '{
"did": "did:web:example.org",
"document": "{\"id\":\"did:web:example.org\",\"verificationMethod\":[]}"
}'
Path Parameters
- walletId: String (required) - The wallet to import the DID into.
Body Parameters
- did: String (required) - The DID to import.
- document: String (required) - The DID document, as a JSON string.
Example Response
{
"did": "did:web:example.org",
"document": { "id": "did:web:example.org", "verificationMethod": [] }
}
List DIDs
Endpoint: GET /wallet/{walletId}/dids | API Reference
Example Request
curl http://localhost:7006/wallet/{walletId}/dids
Path Parameters
- walletId: String (required) - The wallet whose DIDs you want to list.
Example Response
[
{
"did": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6",
"document": { "id": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6" }
}
]
Get a DID
Endpoint: GET /wallet/{walletId}/dids/{did} | API Reference
Example Request
curl http://localhost:7006/wallet/{walletId}/dids/did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6
Path Parameters
- walletId: String (required) - The wallet holding the DID.
- did: String (required) - The DID to fetch. Obtain it from list DIDs or the create/import response.
Example Response
{
"did": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6",
"document": { "id": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6" }
}
Delete a DID
Endpoint: DELETE /wallet/{walletId}/dids/{did} | API Reference
Example Request
curl -X DELETE http://localhost:7006/wallet/{walletId}/dids/did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6
Path Parameters
- walletId: String (required) - The wallet holding the DID.
- did: String (required) - The DID to delete. Obtain it from list DIDs or the create/import response.
Example Response
204 No Content on success, or 404 Not Found if the DID doesn't exist.
Set the Default DID
Set the DID the wallet uses when a receive or present request omits did.
Endpoint: PUT /wallet/{walletId}/dids/{did}/set-default | API Reference
Example Request
curl -X PUT http://localhost:7006/wallet/{walletId}/dids/did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6/set-default
Path Parameters
- walletId: String (required) - The wallet holding the DID.
- did: String (required) - The DID to make the wallet's default.
Example Response
204 No Content on success, or 404 Not Found if the DID doesn't exist in the wallet.
Next Steps
- Receive a credential bound to your DID.
- Manage keys the DIDs are derived from.