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:
| Mode | Use it for |
|---|---|
user | Personal records accessed by their owner. |
group | Shared records accessed by members of the assigned group. |
usergroup | Records accessible through either ownership or group membership. |
perm | Owner, group, and other permissions, including access for callers outside the owning group. |
none | A 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:
| Caller | Read | Update | Delete |
|---|---|---|---|
| Record owner | Yes | Yes | Yes |
| Member of its group | Yes | No | No |
| Unrelated user | No | No | No |
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.