Public Endpoint Reference

This page lists the customer-facing endpoints your application can call directly.

Authentication

All public endpoints use a project API key.

Authorization: Bearer <project-api-key>
Content-Type: application/json

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

unauthorized

GET /v1/config

Returns the authenticated project's feature, action, and role map.

Use it when your application needs a project-scoped authorization snapshot.

Request body: none

Response:

{
  "project": {
    "id": "f89c9a1e-66be-4e77-bf4a-b9e2f6f88d69",
    "name": "Acme App"
  },
  "version": "54fcbda2df94865ba1af0ca2",
  "features": [
    {
      "id": "6ea4a805-a7fa-4136-8995-7edfe15c4a0f",
      "name": "billing",
      "description": "Billing and invoice workflows",
      "actions": [
        {
          "id": "6888fa13-cd1f-4af0-8ddf-c4c0cdb6c7fd",
          "action": "read"
        },
        {
          "id": "79ed1bfa-9ef8-431c-9a15-67c96da7550b",
          "action": "write"
        }
      ]
    }
  ],
  "roles": [
    {
      "id": "d61afad3-d8a6-4701-a414-ab31f8a3b26e",
      "name": "billing-admin",
      "description": "Can manage billing settings",
      "permissions": [
        {
          "feature_id": "6ea4a805-a7fa-4136-8995-7edfe15c4a0f",
          "feature_name": "billing",
          "action_id": "6888fa13-cd1f-4af0-8ddf-c4c0cdb6c7fd",
          "action": "read"
        }
      ]
    }
  ]
}

{
  "error": "project not found"
}

Field notes:

• version is a hash of the current project authorization config
• description is omitted when a feature or role does not define one
• auth failures still return plain-text unauthorized

POST /v1/check

Runs one authorization decision for a subject.

Request body:

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

Response:

{
  "allowed": true,
  "reason": "role:billing-admin"
}

{
  "error": "subject is required"
}

Field notes:

• subject, feature, and action are required
• tenant is optional, but if present it must not be an empty string
• invalid request bodies return { "error": "..." }
• internal evaluation failures fail closed as { "allowed": false, "reason": "error" }
• auth failures still return plain-text unauthorized

For more detail, see Check Endpoint.

POST /v1/check/batch

Runs multiple authorization decisions for the same subject and optional tenant context.

Request body:

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

Response:

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

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

Field notes:

• subject is required
• checks must be a non-empty array
• each item in checks requires feature and action
• request-level failures return { "error": "..." }
• per-item evaluation failures remain 200 OK and produce results[].reason = "error"
• auth failures still return plain-text unauthorized

For more detail, see Check Endpoint.

POST /v1/subjects/upsert

Creates or updates a subject from your application runtime when you need Thauth to reflect current subject assignments programmatically.

Use it when your application owns subject synchronization and wants to push role IDs or override-backed permissions into the project-scoped public plane.

Request body:

{
  "subject_id": "user:alice",
  "subject_type": "user",
  "tenant_id": "tenant_acme",
  "role_ids": [
    "334858ea-4454-4f5e-84ae-afd1c0644d85"
  ],
  "permissions": [
    {
      "feature_id": "6ea4a805-a7fa-4136-8995-7edfe15c4a0f",
      "action": "read",
      "effect": "allow"
    }
  ]
}

Response:

{
  "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": [
    {
      "id": "0fd808a4-a36f-4e5e-95fd-c1a37691f3c7",
      "project_id": "f89c9a1e-66be-4e77-bf4a-b9e2f6f88d69",
      "subject_pk_id": "e18ae2b0-e735-4146-bf7f-4a96d41f3813",
      "role_id": "334858ea-4454-4f5e-84ae-afd1c0644d85",
      "tenant_id": "tenant_acme",
      "created_at": "2026-04-22T09:00:00Z",
      "updated_at": "2026-04-22T09:00:00Z"
    }
  ],
  "permissions": [
    {
      "id": "8e2d8a88-fc27-49d0-881b-a63942f0439d",
      "project_id": "f89c9a1e-66be-4e77-bf4a-b9e2f6f88d69",
      "subject_pk_id": "e18ae2b0-e735-4146-bf7f-4a96d41f3813",
      "feature_id": "6ea4a805-a7fa-4136-8995-7edfe15c4a0f",
      "action": "read",
      "effect": "allow",
      "tenant_id": "tenant_acme",
      "created_at": "2026-04-22T09:00:00Z",
      "updated_at": "2026-04-22T09:00:00Z"
    }
  ]
}

{
  "error": "subject_type is required"
}

Field notes:

• subject_id and subject_type are required
• role_ids must contain UUID strings when provided
• permissions[].feature_id must be a UUID string
• permissions[].effect must be either allow or deny
• common not-found responses are role not found, feature not found, and action not found for this feature
• auth failures still return plain-text unauthorized

If your application only needs customer-facing authorization calls, the public /v1/* endpoints above are the relevant surface.