Authorizations

Overview

Authorization requests (internally called “claims” for compatibility) represent an agent’s request to access a service within a namespace. The lifecycle:

Submit - Service submits authorization request on behalf of agent
Pending - Namespace owner reviews request
Approve/Reject - Owner makes decision
Revoke - Owner can revoke previously approved authorization

Submit Authorization Request

POST /v1/claims

endpoint

Submit an authorization request on behalf of an agent.

Requires service API key and signed headers.

Authentication

Authorization

string

required

Service API key as Bearer token.

Bearer sk_live_...

Plus all standard signed headers including content-digest.

Request Body

namespace

string

required

Target namespace identifier (3-64 characters).Example: acme-corp

public_key

string

required

Agent’s Ed25519 public key (format: ed25519:<base64>).Example: ed25519:LS0tLS1CRUdJTi...

service

string

required

Service slug (must match authenticated service).Example: my-service

agent_ip

string

required

IP address of the agent making the request.Example: 203.0.113.45

nonce

string

required

Unique nonce for replay protection (8-256 characters).Example: abc123xyz789

subject

string

Subject identifier for user-scoped policies (1-256 characters).Example: [email protected]

agent_id

string

Agent identifier (1-128 characters).Example: agent-001

agent_name

string

Human-readable agent name (1-128 characters).Example: Production Agent

Response

claim_id

string

required

Unique claim identifier.

status

string

required

Current claim status: pending, approved, rejected.

Returns 200 with approved or pending if claim already exists
Returns 201 if new claim created

service

string

required

Service slug.

message

string

required

Human-readable status message.

Example Request

curl -X POST 'https://api.sigilum.id/v1/claims' \
  -H 'Authorization: Bearer sk_live_abc123...' \
  -H 'signature-input: sig1=("@method" "@target-uri" "content-digest" "sigilum-namespace" "sigilum-subject" "sigilum-agent-key" "sigilum-agent-cert");created=1705320000;keyid="agent-key-1";alg="ed25519";nonce="n789"' \
  -H 'signature: sig1=:MEUCIQDx...==:' \
  -H 'content-digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:' \
  -H 'sigilum-namespace: my-service-ns' \
  -H 'sigilum-subject: [email protected]' \
  -H 'sigilum-agent-key: ed25519:LS0tLS...' \
  -H 'sigilum-agent-cert: eyJ2ZXJzaW9u...' \
  -H 'Content-Type: application/json' \
  -d '{
    "namespace": "acme-corp",
    "public_key": "ed25519:LS0tLS1CRUdJTi...",
    "service": "my-service",
    "agent_ip": "203.0.113.45",
    "nonce": "abc123xyz789",
    "subject": "[email protected]",
    "agent_id": "agent-001",
    "agent_name": "Production Agent"
  }'

Error Responses

Status	Code	Description
400	`INVALID_REQUEST`	Invalid request body or parameters
401	`SIGNATURE_INVALID`	Invalid signature or API key
403	`FORBIDDEN`	Service slug mismatch
404	`NOT_FOUND`	Namespace or service not found
409	`CONFLICT`	Conflicting claim state
503	`SERVICE_UNAVAILABLE`	Database unavailable

Get Authorization Request

GET /v1/claims/{claimId}

endpoint

Retrieve details for a specific authorization request.

Requires namespace-owner authentication (dashboard cookie).

Path Parameters

claimId

string

required

Claim identifier.

Response

Returns full claim details (see response schema in Namespaces).

Example Request

curl -X GET 'https://api.sigilum.id/v1/claims/claim_abc123' \
  -H 'Cookie: sigilum_token=eyJhbGciOiJIUzI1NiIs...'

Error Responses

Status	Description
401	Not authenticated
403	Not authorized for this namespace
404	Claim not found

Approve Authorization Request

POST /v1/claims/{claimId}/approve

endpoint

Approve a pending authorization request.

Requires namespace-owner authentication.

Path Parameters

claimId

string

required

Claim identifier to approve.

Response

claim_id

string

required

Claim identifier.

status

string

required

Will be approved.

agents_approved

integer

required

Number of approved agents in this namespace.

agents_limit

integer

required

Maximum number of agents allowed in this namespace.

blockchain_tx_status

string

required

Blockchain transaction status: queued (if blockchain enabled).

Example Request

curl -X POST 'https://api.sigilum.id/v1/claims/claim_abc123/approve' \
  -H 'Cookie: sigilum_token=eyJhbGciOiJIUzI1NiIs...'

Error Responses

Status	Description
401	Not authenticated
403	Not authorized for this namespace
404	Claim not found
409	Claim already approved or in invalid state

Reject Authorization Request

POST /v1/claims/{claimId}/reject

endpoint

Reject a pending authorization request.

Requires namespace-owner authentication.

Path Parameters

claimId

string

required

Claim identifier to reject.

Response

claim_id

string

required

Claim identifier.

status

string

required

Will be rejected.

Example Request

curl -X POST 'https://api.sigilum.id/v1/claims/claim_abc123/reject' \
  -H 'Cookie: sigilum_token=eyJhbGciOiJIUzI1NiIs...'

Error Responses

Status	Description
401	Not authenticated
403	Not authorized for this namespace
404	Claim not found

Revoke Authorization

POST /v1/claims/{claimId}/revoke

endpoint

Revoke an approved authorization.

Requires namespace-owner authentication.

Path Parameters

claimId

string

required

Claim identifier to revoke.

Response

claim_id

string

required

Claim identifier.

status

string

required

Will be revoked.

blockchain_tx_status

string

required

Blockchain transaction status: queued (if blockchain enabled).

Example Request

curl -X POST 'https://api.sigilum.id/v1/claims/claim_abc123/revoke' \
  -H 'Cookie: sigilum_token=eyJhbGciOiJIUzI1NiIs...'

Error Responses

Status	Description
401	Not authenticated
403	Not authorized for this namespace
404	Claim not found
409	Claim not in approved state

Webhook Events

When configured, services receive webhook notifications for authorization lifecycle events:

request.submitted - New authorization request created
request.approved - Authorization request approved
request.rejected - Authorization request rejected
request.revoked - Authorization revoked
request.expired - Authorization expired

See Services documentation for webhook configuration.

Sigilum API

Gateway API

Overview

Submit Authorization Request

Authentication

Request Body

Response

Example Request

Error Responses

Get Authorization Request

Path Parameters

Response

Example Request

Error Responses

Approve Authorization Request

Path Parameters

Response

Example Request

Error Responses

Reject Authorization Request

Path Parameters

Response

Example Request

Error Responses

Revoke Authorization

Path Parameters

Response

Example Request

Error Responses

Webhook Events

Build docs developers (and LLMs) love

Sigilum API

Gateway API

​Overview

​Submit Authorization Request

​Authentication

​Request Body

​Response

​Example Request

​Error Responses

​Get Authorization Request

​Path Parameters

​Response

​Example Request

​Error Responses

​Approve Authorization Request

​Path Parameters

​Response

​Example Request

​Error Responses

​Reject Authorization Request

​Path Parameters

​Response

​Example Request

​Error Responses

​Revoke Authorization

​Path Parameters

​Response

​Example Request

​Error Responses

​Webhook Events

Build docs developers (and LLMs) love

Overview

Submit Authorization Request

Authentication

Request Body

Response

Example Request

Error Responses

Get Authorization Request

Path Parameters

Response

Example Request

Error Responses

Approve Authorization Request

Path Parameters

Response

Example Request

Error Responses

Reject Authorization Request

Path Parameters

Response

Example Request

Error Responses

Revoke Authorization

Path Parameters

Response

Example Request

Error Responses

Webhook Events