---
title: "DID Management"
description: "Create, import, list, and delete DIDs in a Wallet API v2 wallet."
stack: "Community Stack (open source) — version 1.1.1"
stack_version: "1.1.1"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/wallet2/did-management
generated: 2026-10-01
---
# DID Management

A [Decentralized Identifier (DID)](https://docs.walt.id/concepts/decentralised-identifiers.md) 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](https://docs.walt.id/community-stack/wallet2/wallets.md)).

**Note:**

**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](https://docs.walt.id/community-stack/wallet2/wallets.md#store-less-wallets). You can override it with [Set the Default DID](#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](https://docs.walt.id/community-stack/wallet2/key-management/overview.md#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`.

**Option: CURL**

**Endpoint:** `POST /wallet/{walletId}/dids/create` | [API Reference](https://docs.walt.id/community-stack/wallet2/full-api-reference.md)

##### Example Request — did:key

```bash
curl -X POST http://localhost:7006/wallet/{walletId}/dids/create \
  -H 'Content-Type: application/json' \
  -d '{ "method": "key" }'
```

##### Example Request — did:web

```bash
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](https://docs.walt.id/community-stack/wallet2/wallets.md).

**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)

---

##### Example Response — did:key

```json
{
  "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

```json
{
  "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).

**Note:**

Already have a DID registered elsewhere? Bring it into the wallet with [Import a DID](#import-a-did).

---

## Import a DID

Import an existing DID and its document.

**Option: CURL**

**Endpoint:** `POST /wallet/{walletId}/dids/import` | [API Reference](https://docs.walt.id/community-stack/wallet2/full-api-reference.md)

##### Example Request

```bash
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

```json
{
  "did": "did:web:example.org",
  "document": { "id": "did:web:example.org", "verificationMethod": [] }
}
```

---

## List DIDs

**Option: CURL**

**Endpoint:** `GET /wallet/{walletId}/dids` | [API Reference](https://docs.walt.id/community-stack/wallet2/full-api-reference.md)

##### Example Request

```bash
curl http://localhost:7006/wallet/{walletId}/dids
```

**Path Parameters**

- **walletId**: _String_ (required) - The wallet whose DIDs you want to list.

---

##### Example Response

```json
[
  {
    "did": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6",
    "document": { "id": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6" }
  }
]
```

---

## Get a DID

**Option: CURL**

**Endpoint:** `GET /wallet/{walletId}/dids/{did}` | [API Reference](https://docs.walt.id/community-stack/wallet2/full-api-reference.md)

##### Example Request

```bash
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](#list-dids) or the create/import response.

---

##### Example Response

```json
{
  "did": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6",
  "document": { "id": "did:key:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6" }
}
```

---

## Delete a DID

**Option: CURL**

**Endpoint:** `DELETE /wallet/{walletId}/dids/{did}` | [API Reference](https://docs.walt.id/community-stack/wallet2/full-api-reference.md)

##### Example Request

```bash
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](#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`.

**Option: CURL**

**Endpoint:** `PUT /wallet/{walletId}/dids/{did}/set-default` | [API Reference](https://docs.walt.id/community-stack/wallet2/full-api-reference.md)

##### Example Request

```bash
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](https://docs.walt.id/community-stack/wallet2/credential-receiving/sd-jwt-vc.md) bound to your DID.
- [Manage keys](https://docs.walt.id/community-stack/wallet2/key-management/overview.md) the DIDs are derived from.