Skip to main content

​
Overview

Namespaces are the core identity primitive in Sigilum. Each namespace maps to a DID (did:sigilum:<namespace>) and serves as the authorization boundary for agents.

​
Resolve Namespace

​
GET /v1/namespaces/{namespace}
endpoint
Resolve a namespace to its current metadata and active claim count.
Requires signed headers with valid agent certificate.

​
Path Parameters

​
namespace
string
required
Namespace identifier (3-64 characters, alphanumeric and hyphens, must start and end with alphanumeric).Example: acme-corp

​
Response

​
did
string
required
Decentralized identifier for the namespace.Example: did:sigilum:acme-corp
​
namespace
string
required
The namespace identifier.
​
owner
string
required
User ID of the namespace owner.
​
created_at
string
required
ISO 8601 timestamp when namespace was created.
​
active
boolean
required
Whether the namespace is currently active.
​
active_claims
integer
required
Number of currently approved authorizations in this namespace.

​
Example Request

curl -X GET 'https://api.sigilum.id/v1/namespaces/acme-corp' \
  -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...'

​
Error Responses

StatusDescription
400Invalid namespace format
401Missing or invalid signature
404Namespace not found
503Database unavailable

​
List Approved Service Authorizations

​
GET /v1/namespaces/claims
endpoint
Get approved authorization records for a service across namespaces (cache feed).
Requires service API key and signed headers. Used by SDK/gateway to build local authorization cache.

​
Authentication

​
Authorization
string
required
Service API key as Bearer token.
Bearer sk_live_...
Plus all standard signed headers.

​
Query Parameters

​
service
string
Service slug filter. Must match the authenticated service when provided.Example: my-service
​
limit
integer
default:"500"
Maximum number of claims to return (1-2000).
​
offset
integer
default:"0"
Number of claims to skip.

​
Response

​
claims
array
required
Array of approved authorization records.
​
claim_id
string
required
Unique claim identifier.
​
namespace
string
required
Namespace the claim belongs to.
​
public_key
string
required
Agent public key (format: ed25519:<base64>).
​
service
string
required
Service slug.
​
approved_at
string
required
ISO 8601 timestamp when claim was approved.
​
subject
string
Subject identifier if provided.
​
agent_id
string
Agent ID if provided.
​
agent_name
string
Agent name if provided.
​
pagination
object
required
Pagination metadata.
​
limit
integer
required
Applied limit.
​
offset
integer
required
Applied offset.
​
total
integer
required
Total approved claims available.
​
has_more
boolean
required
Whether more results exist.

​
Example Request

curl -X GET 'https://api.sigilum.id/v1/namespaces/claims?service=my-service&limit=100' \
  -H 'Authorization: Bearer sk_live_abc123...' \
  -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: my-service-ns' \
  -H 'sigilum-subject: [email protected]' \
  -H 'sigilum-agent-key: ed25519:LS0tLS...' \
  -H 'sigilum-agent-cert: eyJ2ZXJzaW9u...'

​
Error Responses

StatusDescription
401Missing or invalid API key or signature
403Service mismatch (service param doesn’t match authenticated service)

​
Get Namespace Authorization Requests

​
GET /v1/namespaces/{namespace}/claims
endpoint
List authorization requests for a namespace with optional filtering.
Requires namespace-owner authentication (dashboard cookie).

​
Path Parameters

​
namespace
string
required
Namespace identifier.

​
Query Parameters

​
status
string
Filter by claim status.Values: pending, approved, revoked, rejected, expired
​
service
string
Filter by service slug.
​
limit
integer
default:"50"
Maximum number of claims to return (1-200).
​
offset
integer
default:"0"
Number of claims to skip.

​
Response

​
claims
array
required
Array of authorization request records.
​
claim_id
string
required
Unique claim identifier.
​
namespace
string
required
Namespace identifier.
​
service
string
required
Service slug.
​
public_key
string
required
Agent public key.
​
agent_ip
string
required
IP address of agent at submission time.
​
status
string
required
Current claim status: pending, approved, revoked, rejected, expired.
​
created_at
string
required
When claim was created.
​
approved_at
string
When claim was approved (if applicable).
​
revoked_at
string
When claim was revoked (if applicable).
​
approval_tx_hash
string
Blockchain transaction hash for approval (if blockchain enabled).
​
revocation_tx_hash
string
Blockchain transaction hash for revocation (if blockchain enabled).
​
subject
string
Subject identifier.
​
agent_id
string
Agent identifier.
​
agent_name
string
Agent display name.
​
pagination
object
required
Pagination metadata.

​
Example Request

curl -X GET 'https://api.sigilum.id/v1/namespaces/acme-corp/claims?status=pending' \
  -H 'Cookie: sigilum_token=eyJhbGciOiJIUzI1NiIs...'

​
Error Responses

StatusDescription
400Invalid query parameters
401Not authenticated
403Not authorized for this namespace
503Database unavailable

Build docs developers (and LLMs) love

Get started for freeTalk to us