Documentation

Access Control

Cleave checks access for each request using the caller's verified identity and the record's permissions. Your frontend or backend sends ordinary resource requests; it does not need to add ownership filters or permission checks to each query.

An identity provider handles sign-in and issues the token. Cleave verifies that token and decides which records the caller may access. See JWT Authentication for verification settings.

Choose who can access records

Set auth.control_level for the service:

ModeUse it for
userPersonal records accessed by their owner.
groupShared records accessed by members of the assigned group.
usergroupRecords accessible through either ownership or group membership.
permOwner, group, and other permissions, including access for callers outside the owning group.
noneA trusted backend that handles record authorization itself. Token verification can remain enabled.

An identity match does not automatically grant every operation. Read, write, and delete permissions determine what the matching caller can do.

For example, a team contact list can let owners manage their contacts and colleagues read them, while keeping other teams' contacts private:

CallerReadUpdateDelete
Record ownerYesYesYes
Member of its groupYesNoNo
Unrelated userNoNoNo

Configure a team policy

This example uses owner-or-group access and initial permissions that give the owner full access and the group read access:

[auth]
ignore_auth = false
control_level = "usergroup"
initial_perm = "744"
secret = "replace-with-your-deployment-secret"
issuer = "https://identity.example.com/"
audience = "cleave-api"

This example uses shared-secret JWT verification. Supply the same verification settings as your issuer; see JWT Authentication for the complete token contract. initial_perm supplies the initial owner/group/other permissions; the selected control level determines which access categories apply. Existing records retain their configured ownership and permissions.

The signed token identifies the user through sub. For shared records, provide gid for the primary group and, where needed, groups for additional memberships. The identity provider supplies these claims; clients do not choose memberships by adding fields to a resource payload.

Read with the signed-in user's token

Set CLEAVE_TOKEN to a valid token obtained through your sign-in flow:

curl --fail-with-body 'http://127.0.0.1:27896/api/0.0/person' \
  -H "Authorization: Bearer $CLEAVE_TOKEN" \
  -H 'Accept: application/vnd.api+json'

The collection contains records that identity may read. Use the same URL for another user with their own token; Cleave applies that user's access. Adding a filter narrows the results further, without widening the caller's permissions.

Update an accessible record

Set PERSON_ID to an existing contact's ID:

curl --fail-with-body -X PATCH \
  "http://127.0.0.1:27896/api/0.0/person/$PERSON_ID" \
  -H "Authorization: Bearer $CLEAVE_TOKEN" \
  -H 'Content-Type: application/vnd.api+json' \
  --data '{"data":{"type":"person","attributes":{"fname":"Minnie"}}}'

With the team policy above, the owner can update the record. A colleague with read-only group access cannot make the same change, even if they know its ID. Hiding an Edit button improves the interface; Cleave's permission check enforces the restriction when a request actually arrives.

Delete with the same access checks

curl --fail-with-body -X DELETE \
  "http://127.0.0.1:27896/api/0.0/person/$PERSON_ID" \
  -H "Authorization: Bearer $CLEAVE_TOKEN"

Run this only against a disposable example record. The owner can delete under the policy above; a read-only colleague cannot. A valid token alone does not grant write or delete access.

Ownership and application backends

New records can receive ownership from the authenticated identity. Send the resource's application data normally; do not submit ownership or permissions as ordinary editable attributes.

A backend may forward the end user's token so Cleave enforces that user's access. Alternatively, it can use a dedicated application identity and make end-user access decisions itself. In that case Cleave sees the application identity, not the browser user. Keep that token on the backend.

Test the policy from the client's perspective

Try the same collection and record requests with an owner token, a group-member token, and an unrelated user's token. Confirm that readable records appear, read-only callers cannot modify them, and unrelated callers cannot retrieve them.

Missing, expired, or invalid tokens return 401 Unauthorized. Resource policy can also reject requests; record-level restrictions may instead leave no matching record or no permitted changes. Do not assume every access denial returns the same status. Inspect the response as described in Error Responses.

For a working sign-in and permissions walkthrough, see the Node and Python CRM applications in Examples.