Documentation

JWT Authentication

Cleave verifies bearer tokens before repository access when authentication is enabled. It does not issue identities, manage users, store passwords, provide login screens, or replace an identity provider.

Cleave authenticates the token first, then applies its own authorization model. JWT authentication verifies the token signature and registered claims such as iat, exp, nbf, iss, and aud. Cleave authorization then applies roles, ACLs, ownership rules, and record-level permissions to decide whether the authenticated request can access a resource.

Request header

Send the token in the standard Authorization header:

Authorization: Bearer <jwt>

Requests without a bearer token are rejected when auth.ignore_auth is false.

Configuration

Authentication is controlled through the auth configuration block.

[auth]
ignore_auth = false
control_level = "usergroup"
secret = "replace-with-shared-hmac-secret"
issuer = "https://issuer.example.com/"
audience = "cleave-api"
require_exp = true
require_nbf = false
clock_skew_seconds = 60
initial_perm = "744"

Current access-control modes are:

ModeRequired claimsEffect
noneRegistered JWT claims onlyNo owner/group record-access restriction is applied.
userRegistered JWT claims, subRequests are scoped to records owned by the user.
groupRegistered JWT claims, sub; optional gid and groupsRequests are scoped to records assigned to the group.
usergroupRegistered JWT claims, sub; optional gid and groupsRequests can match user or group access.
permRegistered JWT claims, sub; optional gid and groupsApplies owner/group/other permissions for the requested operation.

The default auth.ignore_auth value is true, which is useful for local evaluation but should not be used for protected environments.

Authentication Then Authorization

JWT verification answers whether the request has a valid token from an acceptable issuer for an acceptable audience and time window.

Cleave authorization answers what that authenticated request can do. After token authentication succeeds, Cleave applies its own resource policy, including configured roles, ACL mode, record ownership, group membership, and owner/group/other record permissions.

Those two stages are separate on purpose. The identity provider issues and signs identity; Cleave uses the authenticated claims to enforce repository access.

Registered claims

Every verified token must include iat. Cleave treats iat, exp, and nbf as numeric dates. Numeric date claims may be supplied as JSON numbers or numeric strings.

{
  "iat": 1784479200,
  "exp": 1784482800,
  "nbf": 1784479140,
  "iss": "https://issuer.example.com/",
  "aud": "cleave-api"
}

Claim behavior:

ClaimBehavior
iatRequired. The token must include an issued-at time.
expRequired by default through auth.require_exp = true. Expired tokens are rejected.
nbfRequired when auth.require_nbf = true. If present, it is validated even when not required.
issValidated when auth.issuer is configured.
audValidated when auth.audience is configured. String and array audiences are supported.

auth.clock_skew_seconds allows a small tolerance around time-based registered claims. The default is:

clock_skew_seconds = 60

User identity and group membership

For access-controlled requests, the signed token must identify the user with sub. Include gid for the primary group and groups for additional memberships when using shared resources. This example shows the claims an issuer would sign; choose current iat and exp values when generating a real token:

{
  "iss": "https://issuer.example.com/",
  "aud": "cleave-api",
  "sub": "018f9e70-0000-7000-8000-000000000001",
  "gid": "018f9e70-0000-7000-8000-000000000002",
  "groups": ["018f9e70-0000-7000-8000-000000000002"],
  "iat": 1784479200,
  "exp": 1784482800
}

sub and gid are strings. If gid is omitted, the primary group falls back to sub. Use an explicit group identity when several users share records. If groups is supplied, it must include the primary group.

Cleave uses the verified identity and memberships to evaluate record access. Clients send the token with ordinary API requests; they do not add permission conditions to resource filters. For read, update, and delete examples, see Access Control.

Failure behavior

Cleave rejects unauthorized requests before repository execution. Common failure causes are:

  • missing Authorization header;
  • header that does not start with Bearer ;
  • token that fails signature verification;
  • missing iat;
  • missing exp when auth.require_exp = true;
  • expired exp;
  • nbf in the future;
  • invalid iss when auth.issuer is configured;
  • invalid aud when auth.audience is configured;
  • missing sub for access-controlled requests;
  • malformed iat;
  • malformed exp or nbf;
  • malformed sub, gid, or group membership claims.

Failures return 401 Unauthorized.

Provider boundary

An external identity system should authenticate users and issue the JWT. Cleave verifies the token and enforces repository access. Keep those responsibilities separate:

  • identity provider: login, password policy, MFA, account recovery, token issuance;
  • Cleave: bearer-token verification, claim extraction, ACL enforcement, repository access.