API authentication

The Claresia HTTP API is at https://api.claresia.com (Modes A/B) or https://api.{tenant_slug}.claresia.cloud for Mode C BYOC.

All endpoints require authentication. Two patterns supported:

Caller type	Auth pattern
End-user browser app (Command Center, Hub Browser)	OIDC redirect → JWT in HttpOnly cookie + Authorization header
Service account (your CI, your data pipeline, custom scripts)	OAuth 2.0 Client Credentials → short-lived bearer JWT
Webhook callbacks (your IdP’s SCIM, Slack interactivity)	Signed payload (HMAC-SHA256, header X-Claresia-Signature)

End-user JWT

After SSO, the browser app receives a JWT signed by Claresia:

POST /api/v1/auth/token
Cookie: claresia_session=...; HttpOnly; Secure; SameSite=Strict

200 OK
{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "token_type": "Bearer",
  "refresh_token": "eyJhbGciOi...",
  "refresh_expires_in": 28800
}

• Access token TTL: 5 minutes (sliding refresh)
• Refresh token TTL: 8 hours (absolute)
• Refresh tokens are stored HttpOnly + Secure cookie; never accessible to JS

Headers on subsequent calls

GET /api/v1/hub/records HTTP/1.1
Host: api.claresia.com
Authorization: Bearer eyJhbGciOi...
X-Claresia-Tenant: dainese
X-Claresia-Request-ID: <client-generated UUIDv7>

The X-Claresia-Tenant header is required for all tenant-scoped endpoints (everything except /v1/health and /v1/openapi.json).

Service account auth (OAuth 2.0 Client Credentials)

For server-to-server traffic (your CI, your data warehouse, scheduled jobs):

1. Create a service account in Command Center

Command Center → Settings → Service Accounts → New →

• Name: dainese-ci-pipeline
• Scopes: choose from hub:read, hub:write, roster:read, skill_entitlement:read, telemetry:read, etc.

Returns a client_id + client_secret (shown once).

2. Token exchange

curl -X POST https://api.claresia.com/api/v1/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=svc_dainese_ci' \
  -d 'client_secret=...' \
  -d 'scope=hub:read telemetry:read'

Response:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "hub:read telemetry:read"
}

• Access token TTL: 1 hour
• No refresh token (re-mint via client credentials)

3. Use

curl https://api.claresia.com/api/v1/hub/records \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'X-Claresia-Tenant: dainese'

Scope reference

Scope	Permission
hub:read	Read all Hub record types
hub:write	Write Hub records (typically not granted to external service accounts)
hub:purge	Purge / soft-delete records (admin only)
roster:read	Read user / group roster
roster:write	Modify user / group archetype assignment
skill_entitlement:read	Read per-archetype skill grants
skill_entitlement:write	Modify skill grants
telemetry:read	Read telemetry envelopes
telemetry:write	Emit telemetry envelopes (used by Mode C customer-side connector)
governance:read	Read governance_event records
connector:admin	Manage LLM connector credentials (Mode C control plane only)

Combine scopes with space-delimited values. Scopes follow least-privilege.

Webhook signing

For webhooks Claresia sends to your endpoints (e.g., user lifecycle events, skill invocation alerts), each payload includes:

X-Claresia-Signature: t=1714742400,v1=<hex-hmac-sha256>
X-Claresia-Webhook-Id: wh_2H8j4...
X-Claresia-Tenant: dainese
Content-Type: application/json

Verify by computing HMAC-SHA256(t + "." + body, your_webhook_secret) and comparing to v1.

import hmac
import hashlib

def verify(t: str, body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        f"{t}.".encode("utf-8") + body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Reject if t is older than 5 minutes (replay protection).

Migration: mock-login → real OIDC

Today, the staging Command Center supports a mock-login for development (POST /api/v1/auth/mock-login with arbitrary email). This is not available in production.

The production migration path:

1. WorkOS contract signed (Q1 2026)
2. Real OIDC integration in cc-059 staging
3. Mock-login retired in staging
4. Production cutover with rolling rollback within 24h if issues detected
5. Mock-login flag removed from the codebase

Customers using the dev API today should plan to switch to real OIDC + service account credentials before the Q1 cutover. Talk to your CSM for migration support.

Rate limits

Endpoint class	Per token	Per tenant
Auth (/oauth/token, /auth/*)	10 / min	100 / min
Hub read	1000 / min	10000 / min
Hub write	500 / min	5000 / min
Telemetry ingest	10000 / min	100000 / min
Roster	100 / min	1000 / min
Skill entitlement	100 / min	1000 / min

Throttled requests return 429 Too Many Requests with a Retry-After header.

Error responses

All errors follow the RFC 7807 Problem Details format:

{
  "type": "https://api.claresia.com/errors/invalid-tenant",
  "title": "Invalid tenant",
  "status": 403,
  "detail": "Tenant 'fakeco' does not exist or you do not have access.",
  "instance": "req_01933a8f...",
  "tenant_slug": "fakeco"
}

API versioning

• URL path: /api/v1/...
• v1 is current. v2 will ship behind opt-in Accept: application/vnd.claresia.v2+json header
• 12-month deprecation window from v2 GA
• Breaking changes never silently roll into v1