Getting Started

1. Get a project API key

Your application authenticates to the public /v1/* endpoints with a project API key.

Use that key as:

Authorization: Bearer <api-key>

2. Call the HTTP API directly

Call the public /v1/* endpoints from your backend service. Keep the project API key server-side and use your normal HTTP client, retry, timeout, and tracing conventions.

3. Run the first decision

Call POST /v1/check with a subject, feature, and action.

{
  "subject": "user:alice",
  "feature": "billing",
  "action": "read"
}

If the subject is allowed, Thauth returns:

{
  "allowed": true,
  "reason": "role:analyst"
}

{
  "error": "subject is required"
}

4. Add tenant context when needed

Include tenant when the same subject can have different access across customer workspaces.

{
  "subject": "user:alice",
  "feature": "reports",
  "action": "export",
  "tenant": "tenant_acme"
}

5. Batch checks for UI gating

Use POST /v1/check/batch when one request needs multiple authorization decisions for the same subject and tenant context.

{
  "subject": "user:alice",
  "tenant": "tenant_acme",
  "checks": [
    { "feature": "billing", "action": "read" },
    { "feature": "billing", "action": "write" }
  ]
}

{
  "results": [
    { "feature": "billing", "action": "read", "allowed": true, "reason": "role:analyst" },
    { "feature": "billing", "action": "write", "allowed": false, "reason": "default:deny" }
  ]
}

{
  "error": "batch checks are not available on the current plan"
}

Each batch item still counts as an individual decision for usage.

6. Sync subjects from your app only when needed

Use POST /v1/subjects/upsert if your application is responsible for keeping subject assignments in sync at runtime.

{
  "subject_id": "user:alice",
  "subject_type": "user",
  "role_ids": [
    "334858ea-4454-4f5e-84ae-afd1c0644d85"
  ]
}

{
  "created": true,
  "subject": {
    "id": "e18ae2b0-e735-4146-bf7f-4a96d41f3813",
    "project_id": "f89c9a1e-66be-4e77-bf4a-b9e2f6f88d69",
    "subject_id": "user:alice",
    "subject_type": "user",
    "created_at": "2026-04-22T09:00:00Z",
    "updated_at": "2026-04-22T09:00:00Z"
  },
  "assignments": [],
  "permissions": []
}

{
  "error": "subject_type is required"
}

If the API key is missing or invalid, the current auth middleware responds with plain text:

unauthorized

If your subjects are already managed outside your customer-facing runtime flow, you may only need GET /v1/config, POST /v1/check, and POST /v1/check/batch.