API Reference

These REST endpoints support the AIdenID clearance layer: control-plane auth, issuer identities, inbox evidence, webhooks, target registries, billing, exports, and demo workflows. All endpoints are available at https://api.aidenid.com.

Base URL

https://api.aidenid.com

Authentication

AIdenID supports three authentication models:

• API key auth — For control-plane and supporting API integrations. See the authentication guide.
• Magic-link sessions — For human consumer endpoints (/v1/consumer/*).
• IP-keyed tokens — For free tier (/v1/free/*). No signup required.

# Agent API auth
Authorization: Bearer <api_key>
X-Org-Id: <organization_id>
X-Project-Id: <project_id>

Request format

All request bodies use JSON. Set Content-Type: application/json for POST, PUT, and PATCH requests.

Idempotency

All mutation endpoints (POST, PUT, PATCH, DELETE) require an Idempotency-Key header. This ensures that retried requests do not create duplicate resources. Use a UUID or any unique string per logical operation.

Idempotency-Key: <GENERATED_UNIQUE_KEY>

Response format

All responses return JSON. Successful responses use HTTP 200 or 201 status codes. List endpoints return paginated results with items, total, limit, and offset fields.

Error handling

Errors follow a consistent structure:

{
  "code": "identity_not_found",
  "message": "The requested identity does not exist.",
  "retryable": false,
  "request_id": "req_x1y2z3"
}

See the error codes table in each endpoint section for endpoint-specific errors.

Response headers

API groups