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:
| Mode | Required claims | Effect |
|---|---|---|
none | Registered JWT claims only | No owner/group record-access restriction is applied. |
user | Registered JWT claims, sub | Requests are scoped to records owned by the user. |
group | Registered JWT claims, sub; optional gid and groups | Requests are scoped to records assigned to the group. |
usergroup | Registered JWT claims, sub; optional gid and groups | Requests can match user or group access. |
perm | Registered JWT claims, sub; optional gid and groups | Applies 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:
| Claim | Behavior |
|---|---|
iat | Required. The token must include an issued-at time. |
exp | Required by default through auth.require_exp = true. Expired tokens are rejected. |
nbf | Required when auth.require_nbf = true. If present, it is validated even when not required. |
iss | Validated when auth.issuer is configured. |
aud | Validated 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 = 60User 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
Authorizationheader; - header that does not start with
Bearer; - token that fails signature verification;
- missing
iat; - missing
expwhenauth.require_exp = true; - expired
exp; nbfin the future;- invalid
isswhenauth.issueris configured; - invalid
audwhenauth.audienceis configured; - missing
subfor access-controlled requests; - malformed
iat; - malformed
expornbf; - 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.