Check Endpoint

Authentication

Send a project API key as a bearer token.

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

Single check request

{
  "subject": "user:alice",
  "feature": "secret",
  "action": "reveal",
  "tenant": "project_123",
  "resource": "prod/api/STRIPE_SECRET_KEY"
}

Single check response

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

{
  "error": "subject is required"
}

Field rules

• subject is required
• feature is required
• action is required
• tenant is optional, but if present it must not be an empty string
• resource is optional, but if present it must not be an empty string

Use resource for path-style checks such as dev/api/DATABASE_URL, staging/api/RESEND_API_KEY, prod/payment/STRIPE_SECRET_KEY, or wildcard export checks like dev/api/*.

Fail-closed internal evaluation response:

{
  "allowed": false,
  "reason": "error"
}

Batch checks

Use POST /v1/check/batch when the subject and tenant are the same across several requested permissions.

{
  "subject": "user:alice",
  "tenant": "tenant_acme",
  "checks": [
    { "feature": "secret", "action": "reveal", "resource": "dev/api/DATABASE_URL" },
    { "feature": "secret", "action": "export", "resource": "dev/api/*" },
    { "feature": "secret", "action": "reveal", "resource": "prod/payment/STRIPE_SECRET_KEY" }
  ]
}

Batch 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"
}

Operational notes

• Batch access is plan-gated in the backend
• Each batch item is billed as an individual decision
• Unknown JSON fields are rejected by strict decoding
• Invalid request bodies return a JSON error response
• POST /v1/check returns { "allowed": false, "reason": "error" } when evaluation fails internally
• POST /v1/check/batch returns { "error": "..." } for request-level failures such as invalid bodies or plan-gated access
• POST /v1/check/batch keeps 200 OK for per-item evaluation failures and sets the affected results[].reason to error
• auth failures still return plain-text unauthorized