Test access

The /v1/authz endpoints answer "may this principal do this?" without making the call. Use them to check a policy before you attach it widely, or to find out why a call was denied.

Every endpoint needs iam:authz:simulate. Owners and admins hold it by default.

How these results differ from real calls

These endpoints use the full evaluator. Your normal API calls use the cached permission check described in Policies. The two agree on what is allowed by policies, groups and permission sets, but the full evaluator also applies features that don't affect real calls yet:

So a result of policy_denied, scp_denied, rcp_denied, boundary_exceeded, session_policy_denied or abac_denied describes what Hexel Studio will enforce later, not what happens today: the real call may succeed.

There are other differences to keep in mind:

• Workspace and environment. These endpoints don't check that workspace_id and environment_id exist in your organization. A real call that names a workspace or environment that isn't active in your organization is denied.
• Actions checked at organization level. Some actions, such as workspace:workspace:create, are always checked at organization level by the real API. Test them without workspace_id.
• Roles. You can test members and service users, not roles. A role ID as subject_id returns user_suspended.
• Caching. evaluate and simulate results can be up to 30 seconds old. explain is never cached.

When the subject has no Deny statements and none of the Preview features apply, and you name the same scope as the real call, the answer matches what the real call gets.

Evaluate one action

curl -X POST https://api.hexelstudio.com/v1/authz/evaluate \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "<user-id>",
    "organization_id": "'"$ORG_ID"'",
    "action": "env:env:create",
    "workspace_id": "'"$WORKSPACE_ID"'"
  }'

const res = await fetch("https://api.hexelstudio.com/v1/authz/evaluate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subject_id: "<user-id>",
    organization_id: process.env.ORG_ID,
    action: "env:env:create",
    workspace_id: process.env.WORKSPACE_ID,
  }),
});
if (!res.ok) {
  throw new Error(`Evaluate failed: ${res.status} ${await res.text()}`);
}
const { allowed, reason } = await res.json();
console.log(allowed, reason);

import os
import requests

resp = requests.post(
    "https://api.hexelstudio.com/v1/authz/evaluate",
    headers={"Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}"},
    json={
        "subject_id": "<user-id>",
        "organization_id": os.environ["ORG_ID"],
        "action": "env:env:create",
        "workspace_id": os.environ["WORKSPACE_ID"],
    },
    timeout=10,
)
resp.raise_for_status()
result = resp.json()
print(result["allowed"], result["reason"])

{
  "allowed": true,
  "reason": "policy_allow",
  "cacheable": true,
  "principal": "<user-id>",
  "action": "env:env:create",
  "resource_type": "",
  "workspace_id": "ws_2c3d4e...",
  "environment_id": "",
  "evaluation_ms": 14
}

action, resource_type, resource_id, workspace_id and environment_id echo the request.

Reasons

The steps run in this order, and the first one that decides ends the evaluation:

Explain a decision

POST /v1/authz/explain takes the same body as evaluate and returns every step it ran. Use it to see which step decided.

curl -X POST https://api.hexelstudio.com/v1/authz/explain \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "<user-id>",
    "organization_id": "'"$ORG_ID"'",
    "action": "iam:policy:write"
  }'

{
  "allowed": false,
  "reason": "default_deny",
  "steps": [
    {"step": "principal", "result": "OK", "details": "uid=<user-id> org=org_9a8b7c..."},
    {"step": "user_status", "result": "OK", "details": "ACTIVE"},
    {"step": "org_status", "result": "OK", "details": "ACTIVE"},
    {"step": "scp_check", "result": "OK", "details": "no SCP blocks this action"},
    {"step": "rcp_check", "result": "SKIP", "details": "no resource_type provided"},
    {"step": "boundary_check", "result": "SKIP", "details": "no boundary attached"},
    {"step": "session_policy", "result": "SKIP", "details": "no session"},
    {"step": "explicit_deny", "result": "OK", "details": "no explicit deny"},
    {"step": "policy_allow", "result": "NO_MATCH", "details": "no matching Allow policy"},
    {"step": "default", "result": "DENY", "details": "no policy grants access"}
  ]
}

Each step has a step name, a result (OK, SKIP, ALLOW, DENY, NO_MATCH or FAIL) and details. The reason values are the ones in Reasons. Other step names can appear; they don't change the decision for your organization.

explain does not run ABAC rules, so it can return default_deny where evaluate returns abac_allow.

Simulate several actions

POST /v1/authz/simulate evaluates a list of actions for one subject in one scope. Each action is evaluated as evaluate would.

curl -X POST https://api.hexelstudio.com/v1/authz/simulate \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "su_4f5a6b...",
    "organization_id": "'"$ORG_ID"'",
    "actions": ["workspace:workspace:read", "env:env:create", "iam:policy:write"]
  }'

{
  "results": [
    {"action": "workspace:workspace:read", "allowed": true, "reason": "policy_allow"},
    {"action": "env:env:create", "allowed": true, "reason": "policy_allow"},
    {"action": "iam:policy:write", "allowed": false, "reason": "default_deny"}
  ]
}

List principals with direct grants

GET /v1/authz/expand returns IDs of principals in your organization that have access through two specific kinds of grant:

• users with a permission set assigned directly to them, whatever the set and its scope, and
• principals with a resource permission on the given resource (Preview).

curl "https://api.hexelstudio.com/v1/authz/expand?resource_type=workspace&resource_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{"principals": ["<user-id>"]}

Validate a policy document

POST /v1/authz/validate-policy checks that a policy document is well formed. Send the document as a JSON string in document:

curl -X POST https://api.hexelstudio.com/v1/authz/validate-policy \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document": "{\"Version\":\"2026-02-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"env:env:read\",\"Resource\":\"*\"}]}"}'

{"valid": true, "errors": null}

When the document is not valid, valid is false and errors lists every problem, for example "statement[0]: Effect must be 'Allow' or 'Deny'". Sending document as a JSON object instead of a string returns 400. See Validate a policy for what is checked.

Errors