Introduction
The Sigilum API provides a namespace-based agent identity and authorization system. It manages:- Namespace identity (
did:sigilum:<namespace>) - Authorization request lifecycle (submit, approve, reject, revoke)
- Agent verification and DID document resolution
- Service registration and API key management
- Webhook delivery for authorization events
Base URLs
API Architecture
The Sigilum API follows a role-based architecture:Namespace Owners
- Register and manage namespaces via dashboard authentication (WebAuthn + JWT cookies)
- Create and configure services
- Approve, reject, or revoke authorization requests
- View authorization history for their namespace
Services
- Authenticate using service API keys (Bearer tokens)
- Submit authorization requests on behalf of agents
- Verify agent authorization status
- Receive webhook notifications for authorization lifecycle events
- Cache approved authorizations for performance
Agents
- Present cryptographic identity (Ed25519 public keys)
- Sign all API requests using HTTP message signatures (RFC 9421)
- Use namespace-bound certificates issued by gateway
Authentication Methods
Signed Headers (Service & Agent Requests)
All protected API endpoints require Sigilum signed headers following RFC 9421:RFC 9421 Signature-Input header containing the signature metadata and signed components list.
RFC 9421 Signature header containing the base64-encoded Ed25519 signature.
Namespace identifier bound to the signing certificate.
Subject identifier for user-scoped policy checks. Must be included in signed components.
Agent public key in format
ed25519:<base64>.Base64url-encoded Sigilum agent certificate JSON.
Required for requests with a non-empty body. SHA-256 digest of the exact request body in format
sha-256=:<base64>:.Bearer Token (Service API Key)
Service endpoints require both signed headers and a Bearer token:Cookie Authentication (Dashboard)
Dashboard endpoints use session cookies:Authorization Flow
- Service Registration: Namespace owner creates service and generates API key
- Authorization Request: Service submits claim for agent public key
- Approval: Namespace owner reviews and approves/rejects request
- Verification: Service verifies agent authorization status
- Revocation: Namespace owner can revoke approved authorization
Error Responses
All errors follow a consistent format:Human-readable error message.
Machine-readable error code (e.g.,
SIGNATURE_INVALID, NAMESPACE_NOT_FOUND).Additional error context when available.
Common Error Codes
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | Malformed request or invalid parameters |
| 401 | SIGNATURE_MISSING | Required signed headers not provided |
| 401 | SIGNATURE_INVALID | Signature verification failed |
| 401 | SIGNATURE_EXPIRED | Signature timestamp outside valid window |
| 403 | SIGNATURE_NAMESPACE_MISMATCH | Namespace does not match certificate |
| 403 | FORBIDDEN | Insufficient permissions |
| 404 | NOT_FOUND | Resource does not exist |
| 409 | CONFLICT | Resource already exists or state conflict |
| 503 | SERVICE_UNAVAILABLE | Temporary service unavailability |
Rate Limiting
Rate limits are enforced per API key or authenticated session. Current limits:- Service API requests: 1000 requests per minute
- Dashboard requests: 100 requests per minute
- Verification endpoint: 2000 requests per minute (optimized for high-throughput)
Pagination
List endpoints support pagination with consistent parameters:Maximum number of items to return (1-200 for most endpoints, up to 2000 for approved claims cache).
Number of items to skip before returning results.
SDKs and Tools
Official SDKs and tools:- @sigilum/gateway: Local gateway for agent certificate management and request signing
- @sigilum/sdk: Client SDK for Node.js applications