Fine-grained access

What takes effect today

The two decision paths are explained in What Preview means.

Resource and Condition in policies

A policy statement can have a Resource and a Condition. Hexel Studio stores both and returns them, but does not match either of them in any decision. POST /v1/authz/validate-policy reports a statement without Resource as a problem, and session policies require it, but neither field changes what a statement allows.

Use "Resource": "*" so that your policies say what they do. To limit access to one workspace or environment today, assign a permission set at that scope (see Write policies), or use a role scoped to that workspace or environment: its sessions can act only there (see Roles).

Trust policies are different: their Condition blocks are evaluated. See Roles and Workload identity.

Resource policies

A resource policy is a policy document attached to one resource, identified by a resource type and ID. Your organization can have one resource policy per resource. Resource policies are stored only.

The response adds id (rpol_...), organization_id, created_by_user_id, created_at and updated_at.

You must already hold, across your organization, every action that the document's Allow statements name. Otherwise the call answers 403 with missing_actions, as when you attach a policy.

curl -X POST https://api.hexelstudio.com/v1/resource-policies \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "workspace",
    "resource_id": "<workspace-id>",
    "policy_document": {
      "Version": "2026-02-17",
      "Statement": [
        {"Effect": "Allow", "Action": "workspace:workspace:read", "Resource": "*"}
      ]
    }
  }'

Reading a resource policy needs iam:policy:write, not iam:policy:read.

Relationship tuples and namespaces

Relationship tuples record facts such as "user X is an editor of document Y". A namespace names a kind of object and defines how its relations inherit from each other. A tuple links a subject to an object through a relation. You can store tuples and ask whether a relation holds, but no access decision reads them: they do not grant or deny any API call.

Namespaces

The schema maps each relation to its definition. A relation with "union" also holds for every subject that has one of the listed relations:

{"owner": {}, "editor": {"union": ["owner"]}, "viewer": {"union": ["editor"]}}

relations is a string, so encode the schema:

curl -X POST https://api.hexelstudio.com/v1/namespaces \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "document",
    "relations": "{\"owner\": {}, \"editor\": {\"union\": [\"owner\"]}, \"viewer\": {\"union\": [\"editor\"]}}"
  }'

Tuples

curl -X POST https://api.hexelstudio.com/v1/relations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "document",
    "object_id": "doc-42",
    "relation": "editor",
    "subject_type": "user",
    "subject_id": "<user-id>"
  }'

The response is 201 Created with the tuple (id starts with rt_, plus organization_id and created_at).

To delete a tuple, send the same five required fields to DELETE /v1/relations:

curl -X DELETE https://api.hexelstudio.com/v1/relations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace": "document", "object_id": "doc-42", "relation": "editor", "subject_type": "user", "subject_id": "<user-id>"}'

Check a relation

POST /v1/relations/check answers whether a subject has a relation to an object in your organization.

curl -X POST https://api.hexelstudio.com/v1/relations/check \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace": "document", "object_id": "doc-42", "relation": "viewer", "subject_type": "user", "subject_id": "<user-id>"}'

{"allowed": true}

The relation holds when one of these is true:

1. A tuple matches all five fields exactly.
2. A tuple gives the relation on the object to a group (subject type group, in lower case) of your organization, and the subject ID is a member of that group.
3. The namespace schema lists, under union, another relation that holds by these same rules.

allowed is only an answer to your question. Your application can use it, but Hexel Studio does not use it to decide any API call.

Read and look up tuples

Lookups return stored tuples only. They do not follow groups or union.

Writing, deleting, reading, checking and looking up tuples all need iam:relation:write.

ABAC attributes and policies

Attribute-based access control (ABAC) lets you attach key-value attributes to members, service users and groups, and write rules that allow or deny actions when the attributes match.

ABAC rules are applied only by the full evaluator, and only at the end: when no policy allows the action, the first enabled ABAC policy that matches decides. In practice:

• An ABAC ALLOW policy can turn a "denied" answer of /v1/authz/evaluate or /v1/authz/simulate into "allowed" (reason abac_allow). It does not allow your real API calls. The only other place the full evaluator runs is the check on your organization when one of your principals assumes a role in another organization.
• An ABAC DENY policy cannot take away an action that a policy allows. It only changes the reason of a denial to abac_denied.
• /v1/authz/explain stops before the ABAC step, so it can answer "denied" where evaluate answers "allowed".
• Attributes on roles affect nothing.

Attributes

Setting a key that the entity already has in your organization replaces its value. Attributes belong to your organization: other organizations' rules never see them.

curl -X POST https://api.hexelstudio.com/v1/abac/attributes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "GROUP", "entity_id": "<group-id>", "attribute_key": "department", "attribute_value": "finance"}'

Policies

A condition holds when the principal's own attribute with that key has that value. If the principal has no attribute with that key, it holds when one of the principal's groups has the key with that value.

An ALLOW policy can name only actions you already hold across your organization, otherwise 403 with missing_actions.

curl -X POST https://api.hexelstudio.com/v1/abac/policies \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "finance-read",
    "display_name": "Finance can read workspaces",
    "effect": "ALLOW",
    "actions": ["workspace:workspace:read"],
    "resources": ["*"],
    "conditions": {"department": "finance"},
    "priority": 10
  }'

Tags

Tags are key-value labels on a resource, identified by a resource type and ID. They are stored only: no decision reads them. Tag keys are unique per resource: adding a key that exists replaces its value.

curl -X POST https://api.hexelstudio.com/v1/tags \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource_type": "role", "resource_id": "<role-id>", "key": "team", "value": "payments"}'