Authorization Flow

Sigilum’s authorization flow manages the complete lifecycle of agent access requests, from initial submission through approval, enforcement, and eventual revocation.

Overview

The authorization flow follows a multi-stage lifecycle:

Claim Lifecycle States

1. Pending

Initial state when a service submits an authorization request. Characteristics:

Awaiting namespace owner decision
Not yet enforceable
Notifications sent to owner
Can be approved or rejected

2. Approved

Owner has granted authorization. Characteristics:

Enforceable by gateway
Included in approved claims feed
Can be revoked at any time
Optionally written to blockchain

3. Rejected

Owner has denied authorization (terminal state). Characteristics:

Not enforceable
Cannot be approved without resubmission
Service receives rejection notification

4. Revoked

Previously approved authorization has been revoked (terminal state). Characteristics:

No longer enforceable
Removed from approved claims feed
Service receives revocation notification
Gateway immediately blocks requests

Complete Authorization Flow

End-to-End Sequence

Detailed Steps

Step 1: Claim Submission

Services submit authorization requests on behalf of agents. API Call:

POST /v1/claims
Authorization: Bearer <service-api-key>
Content-Type: application/json

Request Body:

{
  "namespace": "my-namespace",
  "public_key": "z6Mkf5rGeLtXy9h8W3pq7nNxKJCxvZMQRj4tU8sVwXyN9kDp",
  "service": "openai",
  "agent_ip": "192.168.1.100",
  "metadata": {
    "agent_name": "Task Assistant",
    "requested_by": "user-123"
  }
}

Authentication:

The service API key is obtained when registering a service via POST /v1/services. The request must also include valid Sigilum signed headers.

Response:

{
  "claim_id": "claim_abc123xyz",
  "status": "pending",
  "submitted_at": "2024-01-15T10:30:00Z"
}

What Happens:

API validates service API key and signed headers
Checks for duplicate claims (same namespace + public_key + service)
Creates claim record in pending state
Sends notification to namespace owner
Optionally writes to blockchain queue
Returns claim ID to service

Rate Limiting: Claim submission is rate limited per connection_id + namespace:

Default: 30 requests per minute
Configurable: GATEWAY_CLAIM_REGISTRATION_RATE_LIMIT_PER_MINUTE
Rejection: AUTH_CLAIM_SUBMIT_RATE_LIMITED

Step 2: Owner Notification

The namespace owner receives notification through:

Dashboard - Real-time notification in UI
Email - Email alert with approval link
Webhook - Service webhook (if configured)

Notification Payload:

{
  "event": "request.submitted",
  "claim_id": "claim_abc123xyz",
  "namespace": "my-namespace",
  "service": "openai",
  "public_key": "z6Mkf5rG...",
  "agent_ip": "192.168.1.100",
  "metadata": {
    "agent_name": "Task Assistant"
  },
  "submitted_at": "2024-01-15T10:30:00Z",
  "approval_url": "https://sigilum.id/claims/claim_abc123xyz"
}

Step 3: Owner Decision

The namespace owner makes a decision via dashboard or API. Approval:

POST /v1/claims/claim_abc123xyz/approve
Authorization: Bearer <owner-jwt>

Response:

{
  "claim_id": "claim_abc123xyz",
  "status": "approved",
  "approved_at": "2024-01-15T10:35:00Z"
}

Rejection:

POST /v1/claims/claim_abc123xyz/reject
Authorization: Bearer <owner-jwt>

Response:

{
  "claim_id": "claim_abc123xyz",
  "status": "rejected",
  "rejected_at": "2024-01-15T10:35:00Z"
}

What Happens on Approval:

API updates claim status to approved
Webhook sent to service: request.approved
Claim added to approved claims feed
Blockchain event recorded (if enabled)
Gateway begins enforcing authorization on next cache refresh

Approval is idempotent - approving an already approved claim is a no-op.

Step 4: Gateway Enforcement

The gateway enforces approved authorizations on every request. Approved Claims Feed Query:

GET /v1/namespaces/claims
Authorization: Bearer <service-api-key>

Response:

{
  "claims": [
    {
      "namespace": "my-namespace",
      "public_key": "z6Mkf5rG...",
      "service": "openai",
      "status": "approved",
      "approved_at": "2024-01-15T10:35:00Z",
      "claim_id": "claim_abc123xyz"
    }
  ],
  "updated_at": "2024-01-15T10:35:00Z"
}

Gateway Cache Behavior:

Queries approved claims feed periodically (default: every 30 seconds)
Caches claims in memory for fast lookup
Validates claim exists for (namespace, public_key, service) triple
Fails closed if cache is unavailable: AUTH_CLAIMS_UNAVAILABLE

Request Validation Flow:

Extract Identity - Parse sigilum-namespace, sigilum-agent-key from headers
Verify Signature - Validate RFC 9421 signature
Check Nonce - Ensure nonce hasn’t been seen (replay protection)
Lookup Claim - Query local cache for approved claim
Resolve Connector - Load connection config and secrets
Forward Request - Inject auth and proxy to upstream

Error Responses: If authorization fails, gateway returns structured errors:

{
  "error": "Authorization claim required",
  "code": "AUTH_CLAIM_REQUIRED",
  "request_id": "req_xyz789",
  "timestamp": "2024-01-15T10:30:00Z",
  "docs_url": "https://docs.sigilum.id/errors/AUTH_CLAIM_REQUIRED"
}

Gateway Error Codes:

Code	Meaning
`AUTH_HEADERS_INVALID`	Duplicate or malformed signed headers
`AUTH_SIGNATURE_INVALID`	RFC 9421 signature verification failed
`AUTH_SIGNED_COMPONENTS_INVALID`	Missing required signed components
`AUTH_IDENTITY_INVALID`	Invalid Sigilum identity headers
`AUTH_NONCE_INVALID`	Nonce missing or malformed
`AUTH_REPLAY_DETECTED`	Nonce already seen (replay attack)
`AUTH_CLAIMS_UNAVAILABLE`	Claims cache unavailable
`AUTH_CLAIMS_LOOKUP_FAILED`	Claim cache lookup failed
`AUTH_CLAIM_REQUIRED`	No approved claim found
`AUTH_CLAIM_SUBMIT_RATE_LIMITED`	Claim submission rate limit hit
`AUTH_FORBIDDEN`	Generic authorization denial

Step 5: Revocation

Owners can revoke authorization at any time. API Call:

POST /v1/claims/claim_abc123xyz/revoke
Authorization: Bearer <owner-jwt>

Response:

{
  "claim_id": "claim_abc123xyz",
  "status": "revoked",
  "revoked_at": "2024-01-15T11:00:00Z"
}

What Happens:

API updates claim status to revoked
Webhook sent to service: request.revoked
Claim removed from approved claims feed
Blockchain event recorded (if enabled)
Gateway stops enforcing on next cache refresh (typically within 30 seconds)

There is a propagation delay between revocation and enforcement. The gateway’s cache refresh interval (default 30 seconds) determines how quickly revocations take effect.

Alternative Revocation Methods: For immediate revocation without claim ID:

// Smart contract direct revocation
revokeClaimDirect(namespace, publicKey, service)

Verification Endpoint

Services can verify individual authorizations via the verification endpoint. API Call:

GET /v1/verify?namespace=my-namespace&public_key=z6Mkf5rG...&service=openai
Authorization: Bearer <service-api-key>

Response (authorized):

{
  "authorized": true,
  "namespace": "my-namespace",
  "public_key": "z6Mkf5rG...",
  "service": "openai",
  "status": "approved",
  "approved_at": "2024-01-15T10:35:00Z"
}

Response (not authorized):

{
  "authorized": false,
  "namespace": "my-namespace",
  "public_key": "z6Mkf5rG...",
  "service": "openai"
}

Use Cases:

Point verification for specific requests
Pre-flight authorization checks
Service-side validation before expensive operations

The approved claims feed (GET /v1/namespaces/claims) is more efficient for gateways that handle many requests, as it provides batch claim data for caching.

Webhook Delivery

Services can register webhooks to receive authorization lifecycle events.

Webhook Configuration

POST /v1/services/{serviceId}/webhooks
Content-Type: application/json

{
  "url": "https://api.example.com/sigilum/webhooks",
  "events": [
    "request.submitted",
    "request.approved",
    "request.rejected",
    "request.revoked"
  ],
  "secret": "whsec_abc123xyz"
}

Webhook Events

request.submitted - New claim submitted:

{
  "event": "request.submitted",
  "claim_id": "claim_abc123xyz",
  "namespace": "my-namespace",
  "service": "openai",
  "public_key": "z6Mkf5rG...",
  "submitted_at": "2024-01-15T10:30:00Z"
}

request.approved - Claim approved:

{
  "event": "request.approved",
  "claim_id": "claim_abc123xyz",
  "namespace": "my-namespace",
  "service": "openai",
  "public_key": "z6Mkf5rG...",
  "approved_at": "2024-01-15T10:35:00Z"
}

request.rejected - Claim rejected:

{
  "event": "request.rejected",
  "claim_id": "claim_abc123xyz",
  "namespace": "my-namespace",
  "service": "openai",
  "public_key": "z6Mkf5rG...",
  "rejected_at": "2024-01-15T10:35:00Z"
}

request.revoked - Claim revoked:

{
  "event": "request.revoked",
  "claim_id": "claim_abc123xyz",
  "namespace": "my-namespace",
  "service": "openai",
  "public_key": "z6Mkf5rG...",
  "revoked_at": "2024-01-15T11:00:00Z"
}

Webhook Reliability

Webhook delivery is durable with:

Exponential backoff - Retry with increasing delays
Retry window - Configurable via WEBHOOK_RETRY_WINDOW_HOURS
Signature verification - HMAC signature with webhook secret
Terminal failure alerts - Email notification on permanent failure

Blockchain Integration

Sigilum optionally writes authorization events to the blockchain for immutable audit logs.

Blockchain Modes

Configured via BLOCKCHAIN_MODE:

Mode	Behavior	Use Case
`disabled`	Skip blockchain writes	Testing, cost optimization
`sync`	Execute inline (synchronous)	Immediate consistency required
`memory`	In-memory async queue	Local testing
`queue`	Durable queue-backed writes	Production (recommended)

Smart Contract Events

The SigilumRegistry contract emits events:

event ClaimSubmitted(
    uint256 indexed claimId,
    string namespace,
    bytes32 publicKeyHash,
    string service,
    string agentIP
);

event ClaimApproved(
    uint256 indexed claimId,
    string namespace,
    bytes32 publicKeyHash,
    string service
);

event ClaimRevoked(
    uint256 indexed claimId,
    string namespace,
    bytes32 publicKeyHash,
    string service
);

Query Authorization On-Chain:

bool authorized = registry.isAuthorized(namespace, publicKeyHash, service);

Blockchain writes provide an immutable audit log but add latency and cost. Use queue mode in production to decouple blockchain writes from API response time.

Auto-Registration (Gateway)

The gateway can automatically submit claims when an unauthorized request is received. Trigger:

Agent makes signed request to gateway
Gateway verifies signature (valid)
Gateway checks approved claims (not found)
Gateway submits claim to API automatically
Gateway returns AUTH_CLAIM_REQUIRED to agent
Owner receives notification to approve

Rate Limiting: Auto-registration is rate limited to prevent spam:

Per connection_id + namespace pair
Default: 30 requests per minute
Configurable: GATEWAY_CLAIM_REGISTRATION_RATE_LIMIT_PER_MINUTE

Security Considerations

Nonce Replay Protection

Nonces are checked in-memory by the gateway with a default 60-second window. The gateway must receive requests within this window to prevent replay attacks.

Requirements:

Nonce must be unique per request
Nonce must be fresh (within replay window)
Nonce checked against in-memory cache
Process-local only (not distributed)

Signature Verification

All requests must have valid Ed25519 signatures covering:

HTTP method
Request path
Identity headers
Content digest (if body present)

Certificate Validation

The sigilum-agent-cert header must:

Be properly formatted and parseable
Match the namespace in sigilum-namespace
Match the public key in sigilum-agent-key
Have valid signature
Not be expired (if expiry set)

Best Practices

Webhook Signature Verification

Always verify webhook signatures using the webhook secret to prevent spoofing

Cache Approved Claims

Use the claims feed endpoint to cache approved claims locally for performance

Handle Revocation Delay

Account for gateway cache refresh interval (30s default) when revoking

Monitor Rate Limits

Monitor claim submission rate limits to avoid auto-registration failures

Next Steps

Deployment Modes

Learn about managed, enterprise, and local deployment options

Gateway Configuration

Configure gateway settings and rate limits

API Reference

Explore all API endpoints in detail

Gateway API

Learn about gateway error codes and handling

Get Started

Core Concepts

Components

SDKs

Integrations

​Overview

​Claim Lifecycle States

​1. Pending

​2. Approved

​3. Rejected

​4. Revoked

​Complete Authorization Flow

​End-to-End Sequence

​Detailed Steps

​Step 1: Claim Submission

​Step 2: Owner Notification

​Step 3: Owner Decision

​Step 4: Gateway Enforcement

​Step 5: Revocation

​Verification Endpoint

​Webhook Delivery

​Webhook Configuration

​Webhook Events

​Webhook Reliability

​Blockchain Integration

​Blockchain Modes

​Smart Contract Events

​Auto-Registration (Gateway)

​Security Considerations

​Nonce Replay Protection

​Signature Verification

​Certificate Validation

​Best Practices

Webhook Signature Verification

Cache Approved Claims

Handle Revocation Delay

Monitor Rate Limits

​Next Steps

Deployment Modes

Gateway Configuration

API Reference

Gateway API

Build docs developers (and LLMs) love

Overview

Claim Lifecycle States

1. Pending

2. Approved

3. Rejected

4. Revoked

Complete Authorization Flow

End-to-End Sequence

Detailed Steps

Step 1: Claim Submission

Step 2: Owner Notification

Step 3: Owner Decision

Step 4: Gateway Enforcement

Step 5: Revocation

Verification Endpoint

Webhook Delivery

Webhook Configuration

Webhook Events

Webhook Reliability

Blockchain Integration

Blockchain Modes

Smart Contract Events

Auto-Registration (Gateway)

Security Considerations

Nonce Replay Protection

Signature Verification

Certificate Validation

Best Practices

Next Steps