Give a DID a human-readable name

Bind a short agent name such as alice to a hosted did:webvh identifier, so /@alice on your appliance redirects to the DID, and park, re-enable, or release the name later.

Bind a short agent name, such as alice, to a hosted DID so that https://<domain>/@alice on your appliance points to it.

Binding a name adds it to the DID document’s alsoKnownAs list and publishes a new signed version of the DID through your VTA. The appliance then answers /@alice with a redirect to the DID. For how updates are published, see DID lifecycle.

Someone requestsdid.example.com/@alice302 redirectResolves to the DIDdid:webvh:Q1abc…:did.example.com:my-serviceIts DID document lists alice in alsoKnownAsStays in sync:the name resolves only whilethe DID document lists it.

A did:webvh identifier is long and hard to share. An agent name gives people and systems a short, memorable address that resolves to the full DID.

Use this guide when:

  • You want to share a DID as a short /@name address.
  • You need to take a name out of service, bring it back, or give it up.

Prerequisites

  • A DID hosted on your appliance. See Create and manage DIDs.
  • PNM CLI installed and configured against your VTA, with the admin role in the DID’s context.

Step 1. Check the name is free

pnm did-mgmt agent-names check \
  --did did:webvh:Q1abc…:did.example.com:my-service \
  --name alice

A name is 2 to 63 lowercase letters, digits, or hyphens, starting and ending with a letter or digit, and some names are reserved. Availability is checked on the DID’s domain.

Step 2. Bind the name

pnm did-mgmt agent-names set \
  --did did:webvh:Q1abc…:did.example.com:my-service \
  --name alice

PNM prints Agent name bound. once the new version of the DID is published.

Manage a name

TaskCommandEffect
Park a namepnm did-mgmt agent-names disable --did <did> --name aliceThe name stops resolving and is removed from the DID document, but stays reserved to this DID. Cached redirects can last up to 5 minutes. It appears in list as parked.
Bring a parked name backpnm did-mgmt agent-names enable --did <did> --name aliceThe name resolves again.
Release a namepnm did-mgmt agent-names remove --did <did> --name aliceThe name is freed for any DID to claim. You can reclaim it later only if it is still free.

Confirm

Test 1: agent-names list shows the name as resolves

pnm did-mgmt agent-names list \
  --did did:webvh:Q1abc…:did.example.com:my-service

Expected output: the name listed with the state resolves.

Test 2: request to /@alice returns a redirect to the DID

curl -sI "https://did.example.com/@alice"

Expected output: HTTP/2 302, with a location header naming the DID. Replace did.example.com with the host of your appliance’s WebVH URL. Browsers are redirected to the DID’s did.jsonl log instead.

Troubleshooting

SymptomLikely causeFix
check or set reports the name is takenAnother DID on the same domain holds the name, or holds it parked.Choose a different name.
check or set reports the name is reservedThe name is on the appliance’s reserved list.Choose a different name.
set fails with agent names require a hosted DIDThe DID was not created on a hosting appliance.Create the DID on your appliance with pnm did-mgmt dids create --server <id>, then bind the name.
/@alice returns 404The name is parked, released, or not yet bound.Run agent-names list to check the name’s state, and bind or enable it.

Next steps