#Default Requests

If you create many DIDs on the same domain, most of each request is the same: the DID type, the domain, and the service endpoints in the DID Document. Default requests let you save that shared part once on your DID service, so each creation only carries what is unique to the DID.

#When This Is Worth It

Default requests pay off when a service creates many DIDs that share a setup and differ in a few fields. For the DID service that means:

• did:web DIDs on one domain. Onboarding users under your domain. The type, domain and DID Document extras (such as a LinkedDomains service entry that ties the DID to your website) are the same every time. The key, the path and the DID ID are different every time. This is the case this page walks through.
• A did:key format convention. did:key has one real option, useJwkJcsPub, which changes the format of the identifier. If your ecosystem needs one format everywhere, pin it once.

Two operations are a poor fit:

• did:jwk has nothing to pin besides the key itself, and the key is different per DID.
• Keys and paths. These identify the DID. A did:key and a did:jwk are derived from the key, and a did:web is derived from the domain and path. Storing them makes every DID the same DID (see Good to Know).

#What Changes

Without a default, every did:web creation carries the full body:

{
  "type": "single_key_reference",
  "domain": "did.example.com",
  "serviceConfigurationSet": [
    {
      "type": "LinkedDomains",
      "serviceEndpoint": ["https://did.example.com"]
    }
  ],
  "keyReference": "waltid.tenant1.kms1.alice-key",
  "path": "tenant1/alice",
  "didId": "alice"
}

With the first three fields stored as a default, the call becomes:

{
  "keyReference": "waltid.tenant1.kms1.alice-key",
  "path": "tenant1/alice",
  "didId": "alice"
}

The service fills in everything you left out. Anything you do send in the call wins over the stored value.

#Prerequisites

• A DID service with a KMS attached. See Setup and Using KMS for DID Creation.
• Optional: a DID store attached, if you want the created DIDs persisted under their didId.
• A bearer token with the update-default-requests permission and the permission to create the DID type you are setting a default for. Both are needed to store a default.

#Step 1: Store a Default

Store the shared settings with a PUT. The last part of the URL, create-did-web, names the API call the default applies to: the one behind POST /v1/{target}/did-service-api/dids/create/web. The body is an ordinary did:web creation request. Leave out every field that changes per DID, and always include type.

curl -X 'PUT' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/did-service-api/dids/default-requests/create-did-web' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "single_key_reference",
  "domain": "did.example.com",
  "serviceConfigurationSet": [
    {
      "type": "LinkedDomains",
      "serviceEndpoint": ["https://did.example.com"]
    }
  ]
}'

{
  "type": "single_key_reference",
  "domain": "did.example.com",
  "serviceConfigurationSet": [
    {
      "type": "LinkedDomains",
      "serviceEndpoint": ["https://did.example.com"]
    }
  ]
}

#Step 2: Create a DID

Send only what is specific to this DID: its key, its path and its ID.

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/did-service-api/dids/create/web' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "keyReference": "waltid.tenant1.kms1.alice-key",
  "path": "tenant1/alice",
  "didId": "alice"
}'

{
  "id": "waltid.tenant1.did-store1.alice",
  "did": "did:web:did.example.com:tenant1:alice",
  "document": {
    "id": "did:web:did.example.com:tenant1:alice",
    "verificationMethod": [ ... ],
    "service": [
      {
        "id": "did:web:did.example.com:tenant1:alice#...",
        "type": "LinkedDomains",
        "serviceEndpoint": "https://did.example.com"
      }
    ]
  }
}

#Override Part of the Default

To change one thing, send only that. This request creates a DID on another domain and keeps the stored type and service entry:

{
  "keyReference": "waltid.tenant1.kms1.bob-key",
  "domain": "other.example.org",
  "path": "bob",
  "didId": "bob-other"
}

#Pin the did:key Format

did:key creation has one option worth pinning, useJwkJcsPub. It defaults to true, which produces the jwk_jcs-pub form (did:key:z2dm…). Set it to false to produce the classic multibase form (did:key:zDna… for a P-256 key) on every creation.

curl -X 'PUT' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/did-service-api/dids/default-requests/create-did-key' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "useJwkJcsPub": false
}'

{
  "useJwkJcsPub": false
}

Later POST …/dids/create/key calls only need keyReference and, if you store the DID, a didId.

#Good to Know

• Never store the key, the path or the didId. A DID is defined by them. Storing a path makes every DID did:web:…:{path}, and storing a key makes every did:key or did:jwk identical. The calls still succeed, each with 201, and the DID store ends up with several records for the same DID.
• A stored key field follows you into other shapes. If the default holds keyReference and a call switches to type: "key_reference_set", the merged request contains both keyReference and keyReferenceSet and fails with 400 (unknown key). Store only the fields that every caller's shape has in common.
• Same key, same did:key. Creating a did:key from one key twice yields the same identifier, whatever didId you use.
• Defaults are not guardrails. Anyone allowed to create DIDs can override any stored field in their own call.
• Each operation has its own default. create-did-web, create-did-key and create-did-jwk are separate.
• Explicit values win, including false over a stored true. Arrays and primitives are replaced wholesale, so a call that sends serviceConfigurationSet replaces the stored list.

#Read or Remove a Default

• List all stored defaults: GET /v1/{target}/did-service-api/dids/default-requests (needs view-default-requests).
• Read one: GET …/default-requests/create-did-web. Returns 404 if none is stored.
• Remove one: DELETE …/default-requests/create-did-web. Returns 204, also when nothing was stored.

Full details, permissions and the other services that support default requests: Default Requests.