Skip to main content

​
Overview

Service management endpoints allow namespace owners to register services, generate API keys, and configure webhooks through the dashboard or API.
All service management endpoints require dashboard authentication (cookie-based session) and return data scoped to the authenticated namespace owner.

​
Services

​
List Services

​
GET /v1/services
endpoint
List all services for the authenticated namespace owner.
Authentication: Cookie-based session Response:
​
services
array

​
Create Service

​
POST /v1/services
endpoint
Register a new service for your namespace.
Authentication: Cookie-based session Request Body:
​
slug
string
required
Service slug (lowercase, alphanumeric, hyphens allowed)
​
name
string
required
Human-readable service name
​
description
string
Optional service description
Response: Returns the created service object (201 Created)

​
Get Service

​
GET /v1/services/{serviceId}
endpoint
Retrieve details for a specific service.
Path Parameters:
​
serviceId
string
required
Service UUID
Response: Returns the service object

​
Update Service

​
PATCH /v1/services/{serviceId}
endpoint
Update service name or description.
Request Body:
​
name
string
Updated service name
​
description
string
Updated description

​
Delete Service

​
DELETE /v1/services/{serviceId}
endpoint
Permanently delete a service. This also deletes all associated API keys and webhooks.
This action is irreversible. All authorization requests associated with this service will become orphaned.

​
API Keys

​
List API Keys

​
GET /v1/services/{serviceId}/keys
endpoint
List all API keys for a service.
Response:
​
keys
array
Full API key values are only returned once at creation time. Store them securely.

​
Create API Key

​
POST /v1/services/{serviceId}/keys
endpoint
Generate a new API key for the service.
Response:
​
key
string
The full API key (only returned once)
​
id
string
Key ID for future reference
​
prefix
string
Key prefix for identification
Example Response: 
{
  "key": "sgl_sk_prod_1234567890abcdef...",
  "id": "key_abc123",
  "prefix": "sgl_sk_p"
}
Store the full API key securely. It cannot be retrieved again after creation.

​
Revoke API Key

​
DELETE /v1/services/{serviceId}/keys/{keyId}
endpoint
Revoke an API key. Revoked keys cannot be used for new requests.
Path Parameters:
​
keyId
string
required
The key ID to revoke

​
Webhooks

Service webhooks receive durable delivery of authorization lifecycle events.

​
List Webhooks

​
GET /v1/services/{serviceId}/webhooks
endpoint
List all webhook configurations for a service.
Response:
​
webhooks
array

​
Create Webhook

​
POST /v1/services/{serviceId}/webhooks
endpoint
Register a new webhook endpoint for authorization events.
Request Body:
​
url
string
required
HTTPS URL to receive webhook events
​
events
array
Array of event types to subscribe to (defaults to all events)Supported events:
  • request.submitted - New authorization request
  • request.approved - Request approved
  • request.rejected - Request rejected
  • request.revoked - Authorization revoked
Response:
​
id
string
Webhook ID
​
secret
string
Webhook signing secret (only returned once)
Use the webhook secret to verify event signatures using HMAC-SHA256.

​
Delete Webhook

​
DELETE /v1/services/{serviceId}/webhooks/{webhookId}
endpoint
Remove a webhook configuration. No further events will be delivered.
Path Parameters:
​
webhookId
string
required
Webhook ID to delete

​
Webhook Event Format

All webhook events are delivered as POST requests with the following structure: 
{
  "event": "request.approved",
  "timestamp": "2024-03-04T12:00:00Z",
  "data": {
    "claim_id": "claim_abc123",
    "namespace": "acme",
    "service": "api-gateway",
    "agent_key": "did:key:z6Mk...",
    "status": "approved"
  }
}
Event Signature: Each webhook request includes a X-Sigilum-Signature header containing an HMAC-SHA256 signature: 
X-Sigilum-Signature: t=<timestamp>,v1=<signature>
Verify the signature using your webhook secret: 
const payload = `${timestamp}.${requestBody}`;
const expectedSignature = crypto
  .createHmac('sha256', webhookSecret)
  .update(payload)
  .digest('hex');

​
Usage Example

Complete workflow for setting up a service:
1

Create a service

POST /v1/services
{
  "slug": "api-gateway",
  "name": "API Gateway",
  "description": "Main API gateway service"
}
2

Generate an API key

POST /v1/services/{serviceId}/keys

# Response: store this key securely
{
  "key": "sgl_sk_prod_abc123...",
  "id": "key_xyz789"
}
3

Configure a webhook

POST /v1/services/{serviceId}/webhooks
{
  "url": "https://api.example.com/webhooks/sigilum",
  "events": ["request.approved", "request.revoked"]
}
4

Use the API key

The service can now submit authorization requests using the API key:
curl -X POST https://api.sigilum.id/v1/claims \
  -H 'Authorization: Bearer sgl_sk_prod_abc123...' \
  -H 'signature-input: ...' \
  -H 'signature: ...' \
  # ... additional signed headers

​
Next Steps

Authorization Flow

Submit and manage authorization requests

Verification

Verify agent authorization status

Dashboard Auth

Authenticate to manage your namespace

Webhooks Guide

Learn about webhook delivery and retry logic

Build docs developers (and LLMs) love

Get started for freeTalk to us