Admin Operations¶

Admin endpoints require API key authentication via the x-api-key header.

Witness Management¶

Add Witness¶

• POST /api/admin/witnesses
• Headers: x-api-key: <WEBVH_ADMIN_API_KEY>
• Body:

  {
    "id": "did:key:z6Mk...",
    "label": "Example Witness Service",
    "invitationUrl": "https://witness.example.com/oob-invite?oob=<base64_encoded_invitation>"
  }
  

• Decodes the invitation, stores it, and creates a short URL in the registry

Remove Witness¶

• DELETE /api/admin/witnesses/{multikey}
• Headers: x-api-key: <WEBVH_ADMIN_API_KEY>
• Removes a witness from the registry

Policy Management¶

Get Parameters¶

• GET /api/admin/parameters
• Headers: x-api-key: <WEBVH_ADMIN_API_KEY>
• Returns the parameters generated from the active policy
• Includes witness configuration, method version, and other policy-driven settings

Witness Management¶

Automatic Registration¶

If both WEBVH_WITNESS_ID and WEBVH_WITNESS_INVITATION are set, the server will automatically:

1. Decode the invitation from the URL
2. Store the invitation using the witness DID as the key
3. Update the witness registry with a short URL (https://{DOMAIN}/api/invitations?_oobid={witness_key})
4. Update the invitation if it changes on restart

Invitation Lookup¶

Witness invitations can be retrieved via the root endpoint:

• GET /api/invitations?_oobid={witness_key}
• Returns the stored invitation as JSON
• The witness_key is the multikey portion of the did:key identifier

Short URLs¶

The server generates short URLs for witness invitations in the format:

https://{DOMAIN}/api/invitations?_oobid={witness_key}

These URLs are: - Stored in the witness registry as serviceEndpoint - Included in the server's DID document under WitnessInvitation services - Resolvable via the root endpoint to return the full invitation JSON