POST /v1/tenants/{tenant_id}/permissions/checkThe Check API answers resource-based authorization questions of the form: “Can user U perform action Y on resource Z?”
Permify evaluates the check by walking the relationship graph defined in your schema. It runs concurrent queries for each branch of the permission expression (or / and) and short-circuits as soon as a definitive result is found.
Path Parameters The tenant identifier. Use the pre-inserted default tenant t1 if you are not using multi-tenancy. Must match ^([a-zA-Z0-9_\-@\.:+]{1,128}|\*)$.
Request Body Controls schema version and caching behavior for this request. Pin the check to a specific schema version. Leave empty to use the latest version.
A token returned by a previous write operation. Pass it here to read your own writes and avoid stale cache results.
Maximum recursion depth for relationship graph traversal. Must be >= 3. Recommended value: 20.
The resource on which the permission is being checked. The entity type as defined in your schema (e.g. repository, document).
The unique identifier of the entity instance.
The permission or relation name to check (e.g. edit, view, push). Must match ^[a-zA-Z_]{1,64}$.
The subject (user or user set) whose access is being evaluated. The subject entity type (e.g. user).
The unique identifier of the subject.
An optional relation on the subject, used for user-set references (e.g. member).
Contextual data injected dynamically at check time — useful for attribute-based (ABAC) checks without writing tuples. Temporary relationship tuples that exist only for the duration of this request.
Temporary attribute values that exist only for the duration of this request.
Arbitrary key-value pairs available to rule expressions in the schema.
Response The authorization decision. One of:
RESULT_ALLOWED — the subject is authorizedRESULT_DENIED — the subject is not authorized The number of individual sub-checks performed to reach the decision.
Examples Relationship-based check curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/permissions/check' \ --header 'Content-Type: application/json' \ --data-raw '{ "metadata": { "snap_token": "", "schema_version": "", "depth": 20 }, "entity": { "type": "repository", "id": "1" }, "permission": "edit", "subject": { "type": "user", "id": "1", "relation": "" } }'
Request body { "metadata" : { "snap_token" : "" , "schema_version" : "" , "depth" : 20 }, "entity" : { "type" : "repository" , "id" : "1" }, "permission" : "edit" , "subject" : { "type" : "user" , "id" : "1" , "relation" : "" } }
Response { "can" : "RESULT_ALLOWED" , "metadata" : { "check_count" : 3 } }
Attribute-based check with context data { "metadata" : { "snap_token" : "" , "schema_version" : "" , "depth" : 20 }, "entity" : { "type" : "organization" , "id" : "1" }, "permission" : "hr_manager" , "subject" : { "type" : "user" , "id" : "1" }, "context" : { "data" : { "ip_address" : "192.158.1.38" } } }
Error Codes HTTP Status Description 400Bad request — missing or invalid fields 401Unauthorized — invalid or missing bearer token 404Tenant not found 429Rate limit exceeded 500Internal server error
