DID Resolution

Overview

Sigilum namespaces are identified by Decentralized Identifiers (DIDs) following the did:sigilum:<namespace> method. DID documents expose the namespace’s current authorization state, including:

Verification methods (agent public keys)
Service endpoints for approved authorizations
Controller information
Namespace metadata

DID Format

did:sigilum:<namespace>

Examples:

did:sigilum:acme-corp
did:sigilum:my-company
did:sigilum:example-namespace

Resolve DID Document

GET /.well-known/did/{did}

endpoint

Resolve a did:sigilum:<namespace> DID to its DID document.

Requires signed headers with valid agent certificate.

Path Parameters

did

string

required

DID value (must match pattern did:sigilum:<namespace>).Example: did:sigilum:acme-corp

Response Headers

Content-Type

string

application/did+json (preferred)
application/json (also supported)

Response Body

@context

array

required

JSON-LD context for DID document.Value: ["https://www.w3.org/ns/did/v1"]

string

required

The DID identifier.Example: did:sigilum:acme-corp

controller

string

required

DID controller (typically same as id for self-sovereign namespaces).

created

string

required

ISO 8601 timestamp when namespace was created.

updated

string

required

ISO 8601 timestamp when DID document was last updated.

verificationMethod

array

required

Array of verification methods (agent public keys with authorization status).

string

required

Verification method identifier.Format: {did}#agent-{index}

type

string

required

Key type: Ed25519VerificationKey2020

publicKeyBase64

string

required

Base64-encoded public key bytes.

service

string

required

Service slug this key is authorized for.

status

string

required

Authorization status: approved, pending, revoked, rejected

Example Request

curl -X GET 'https://api.sigilum.id/.well-known/did/did:sigilum:acme-corp' \
  -H 'Accept: application/did+json' \
  -H 'signature-input: sig1=("@method" "@target-uri" "sigilum-namespace" "sigilum-subject" "sigilum-agent-key" "sigilum-agent-cert");created=1705320000;keyid="agent-key-1";alg="ed25519";nonce="n123"' \
  -H 'signature: sig1=:MEUCIQDx...==:' \
  -H 'sigilum-namespace: acme-corp' \
  -H 'sigilum-subject: [email protected]' \
  -H 'sigilum-agent-key: ed25519:LS0tLS...' \
  -H 'sigilum-agent-cert: eyJ2ZXJzaW9u...'

DID Resolution Envelope

GET /1.0/identifiers/{did}

endpoint

Resolve DID with full resolution metadata envelope.

Returns DID Resolution Result as defined by W3C DID specification.

Response Headers

Content-Type

string

application/ld+json;profile="https://w3id.org/did-resolution"

Response Body

@context

string

required

DID resolution context URL.

didDocument

object

required

The resolved DID document (same structure as /.well-known/did/{did} response).

didDocumentMetadata

object

required

Metadata about the DID document.

created

string

required

When the DID was created.

updated

string

required

When the DID was last updated.

deactivated

boolean

Whether the namespace has been deactivated. When true, historical authorization state exists but the namespace owner is no longer active.

didResolutionMetadata

object

required

Metadata about the resolution process.

contentType

string

required

Content type of the response.

Example Request

curl -X GET 'https://api.sigilum.id/1.0/identifiers/did:sigilum:acme-corp' \
  -H 'Accept: application/ld+json' \
  -H 'signature-input: sig1=("@method" "@target-uri" "sigilum-namespace" "sigilum-subject" "sigilum-agent-key" "sigilum-agent-cert");created=1705320000;keyid="agent-key-1";alg="ed25519";nonce="n456"' \
  -H 'signature: sig1=:MEUCIQDx...==:' \
  -H 'sigilum-namespace: acme-corp' \
  -H 'sigilum-subject: [email protected]' \
  -H 'sigilum-agent-key: ed25519:LS0tLS...' \
  -H 'sigilum-agent-cert: eyJ2ZXJzaW9u...'

Use Cases

Identity Verification

Verify namespace ownership and agent authorization:

import { resolveDID } from '@sigilum/sdk';

const didDoc = await resolveDID('did:sigilum:acme-corp');

// Check if specific agent is authorized
const agentKey = 'LS0tLS1CRUdJTi...';
const authorized = didDoc.verificationMethod.some(
  vm => vm.publicKeyBase64 === agentKey && vm.status === 'approved'
);

if (authorized) {
  console.log('Agent is authorized');
} else {
  console.log('Agent is not authorized');
}

Service Discovery

Discover which services an agent is authorized for:

const didDoc = await resolveDID('did:sigilum:acme-corp');

const agentKey = 'LS0tLS1CRUdJTi...';
const services = didDoc.verificationMethod
  .filter(vm => vm.publicKeyBase64 === agentKey && vm.status === 'approved')
  .map(vm => vm.service);

console.log('Authorized services:', services);
// Output: ['my-service', 'other-service']

Audit Trail

Track authorization history:

const didDoc = await resolveDID('did:sigilum:acme-corp');

console.log('Namespace created:', didDoc.created);
console.log('Last updated:', didDoc.updated);

const summary = {
  approved: 0,
  pending: 0,
  revoked: 0,
  rejected: 0,
};

for (const vm of didDoc.verificationMethod) {
  summary[vm.status]++;
}

console.log('Authorization summary:', summary);
// Output: { approved: 5, pending: 2, revoked: 1, rejected: 0 }

Error Responses

Status	Code	Description
400	`INVALID_DID`	DID format is invalid
401	`SIGNATURE_INVALID`	Invalid or missing signed headers
404	`DID_NOT_FOUND`	Namespace does not exist

Deactivated Namespaces

When a namespace owner deletes their account, the DID document is marked as deactivated:

{
  "didDocumentMetadata": {
    "deactivated": true,
    "created": "2024-01-15T10:30:00Z",
    "updated": "2024-02-20T08:15:00Z"
  }
}

Deactivated namespaces:

Retain historical authorization data
Cannot approve new authorizations
Existing approved authorizations are effectively revoked
DID document remains resolvable for audit purposes

Integration with Blockchain

When blockchain integration is enabled (BLOCKCHAIN_MODE is not disabled), namespace registration and key events are recorded on-chain:

Namespace registration: Transaction hash in registration_tx_hash
Authorization approval: Transaction hash in approval_tx_hash
Authorization revocation: Transaction hash in revocation_tx_hash

These transaction hashes provide an immutable audit trail that can be verified independently.

Caching Recommendations

DID documents can be cached with appropriate TTLs:

Approved authorizations: Cache for 5-15 minutes
Pending/rejected: Cache for 1 minute or less
Metadata: Cache for 1 hour

Invalidate cache on webhook events:

request.approved → Refresh DID document
request.revoked → Refresh DID document
Namespace updates → Refresh DID document

Security Considerations

Public Key Encoding

publicKeyBase64 contains the raw Ed25519 public key bytes (32 bytes) encoded as base64. To use with the verification API, prepend ed25519: prefix.

Controller Verification

Always verify the controller field matches the expected namespace DID to prevent DID document spoofing.

Signature Verification

When using DID documents to verify signatures, ensure:

The signing key appears in verificationMethod
The key’s status is approved
The key’s service matches your service
The DID document is current (check updated timestamp)

Sigilum API

Gateway API

Overview

DID Format

Resolve DID Document

Path Parameters

Response Headers

Response Body

Example Request

DID Resolution Envelope

Response Headers

Response Body

Example Request

Use Cases

Identity Verification

Service Discovery

Audit Trail

Error Responses

Deactivated Namespaces

Integration with Blockchain

Caching Recommendations

Security Considerations

Public Key Encoding

Controller Verification

Signature Verification

Build docs developers (and LLMs) love

Sigilum API

Gateway API

​Overview

​DID Format

​Resolve DID Document

​Path Parameters

​Response Headers

​Response Body

​Example Request

​DID Resolution Envelope

​Response Headers

​Response Body

​Example Request

​Use Cases

​Identity Verification

​Service Discovery

​Audit Trail

​Error Responses

​Deactivated Namespaces

​Integration with Blockchain

​Caching Recommendations

​Security Considerations

​Public Key Encoding

​Controller Verification

​Signature Verification

Build docs developers (and LLMs) love

Overview

DID Format

Resolve DID Document

Path Parameters

Response Headers

Response Body

Example Request

DID Resolution Envelope

Response Headers

Response Body

Example Request

Use Cases

Identity Verification

Service Discovery

Audit Trail

Error Responses

Deactivated Namespaces

Integration with Blockchain

Caching Recommendations

Security Considerations

Public Key Encoding

Controller Verification

Signature Verification