Organization-level DIDs

Organization-level DIDs are scoped to the entire organization, not to a specific tenant. Use this model when a DID should represent the organization itself or be shared across multiple tenants — for example, a central issuer DID or an admin identity.

When to use organization-level DIDs

Use organization-level when…Example
The DID represents the organization as a wholedid:web:org.example.com:issuer
One issuer serves credentials across all tenantsCentral OID4VCI issuer DID
You want shorter DID paths without a tenant segmentdid:web:domain.com:alice instead of did:web:domain.com:tenant:alice

For per-tenant isolation, use Tenant-level DIDs instead.

DID format and resolution

Value
DID patterndid:web:{domain}:{user}
Example DIDdid:web:waltid.enterprise-sandbox.waltid.dev:alice
Resolution URLhttps://waltid.enterprise-sandbox.waltid.dev/alice/did.json

When creating a DID via the DID Service, set the path to the user segment directly (no tenant prefix):

{
  "domain": "waltid.enterprise-sandbox.waltid.dev",
  "path": "alice"
}

See Create a did:web for the full API.

Setup overview

Organization-level DIDs require two configuration steps:

  1. Create an organization-level DID Registry service at the organization scope (not inside a tenant)
  2. Register it as the root DID registry in the organization configuration via rootDidRegistry

Loading diagram...

Step 1: Create the organization-level DID Registry

Create the registry at the organization level. The target is {organizationID}.{serviceID} — no tenant segment.

CURL

Endpoint: /v1/{target}/resource-api/services/create | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "did-registry"
}'

Path Parameters

  • orgID — Organization base URL or host alias (e.g. waltid.enterprise-sandbox.waltid.dev).
  • target — resourceIdentifier — Organization + service ID: {organizationID}.{serviceID}, e.g. waltid.did-registry-main

Header Parameters

  • Authorization — Bearer token for Enterprise Stack authentication. Format: Bearer {yourToken}.

Body Parameters

  • type — serviceType — Must be did-registry

Response Codes

  • 201 — Service created successfully.

Remember to add a DID Store as a dependency on this registry service, as described in Setup.

Step 2: Register the root DID Registry

Tell the organization which registry service handles organization-level DIDs by setting rootDidRegistry.

CURL

Endpoint: /v1/organization/update-config | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/organization/update-config' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "rootDidRegistry": "waltid.did-registry-main"
}'

Path Parameters

  • orgID — Organization base URL (same as above).

Header Parameters

  • Authorization — Bearer token for Enterprise Stack authentication. Format: Bearer {yourToken}.

Body Parameters

  • rootDidRegistry — resourceIdentifier — Full ID of the organization-level DID Registry service, e.g. waltid.did-registry-main

Response Codes

  • 200 — Configuration updated successfully.

Step 3: Create and verify a DID

Create a did:web using the DID Service with an organization-scoped path, then verify resolution:

# Create the DID (via DID Service)
# Then verify:
curl https://waltid.enterprise-sandbox.waltid.dev/alice/did.json

Next steps

Last updated on August 24, 2026
Create did:webResolution