Just-in-time access and approvals

What works today

• Requests and workflows are stored in your organization, with who did what and when.
• The rules about who may decide are enforced: nobody approves their own JIT request or decides their own approval request, approvers must hold the permission and, for workflows, the approver list and approver role.
• The JIT state machine is enforced: a status change that is not allowed answers 409.

To give temporary access today, add the person to a role's trust policy and let them assume the role. A role session ends when it expires, and you can end every session of a role at once. See Roles.

JIT access requests

A JIT request asks for a role, optionally in one workspace or environment, for a number of minutes. The requester is always the caller, in the caller's organization.

Permissions

Create a request

POST /v1/jit needs iam:jit:write.

curl -X POST https://api.hexelstudio.com/v1/jit \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "<role-id>",
    "reason": "Investigate failed deployment",
    "ticket_id": "INC-1234",
    "duration_minutes": 60
  }'

The response is 201 Created:

{
  "id": "jit_...",
  "user_id": "<user-id>",
  "role_id": "<role-id>",
  "organization_id": "<org-id>",
  "reason": "Investigate failed deployment",
  "ticket_id": "INC-1234",
  "duration_minutes": 60,
  "status": "PENDING",
  "created_at": "2026-10-20T09:00:00Z"
}

user_id and organization_id come from your token. status always starts as PENDING. As the request moves on, the response also carries approved_by_user_id, approved_at, activated_at, expires_at, revoked_at and revoked_by_user_id.

Change the status

PATCH /v1/jit/{request_id}/status with {"status": "..."}.

REJECTED, REVOKED and EXPIRED are final.

curl -X PATCH https://api.hexelstudio.com/v1/jit/<request-id>/status \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "APPROVED"}'

{"status": "APPROVED"}

{"error": "status change not allowed", "from": "PENDING", "to": "ACTIVE"}

Read requests

curl "https://api.hexelstudio.com/v1/jit?status=PENDING" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Approval workflows

An approval workflow defines who must approve a type of change and how many approvals it needs. Approval requests are filed against a workflow and settled by approvers' decisions.

Permissions

Workflows

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

curl -X POST https://api.hexelstudio.com/v1/approvals/workflows \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production policy changes",
    "workflow_type": "POLICY_CHANGE",
    "approver_role": "org_admin",
    "min_approvals": 2
  }'

Requests

The requester is the caller. status starts as PENDING and becomes APPROVED or REJECTED through decisions.

curl -X POST https://api.hexelstudio.com/v1/approvals/requests \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "<workflow-id>",
    "request_type": "attach_policy",
    "request_data": {"policy_id": "<policy-id>", "target_type": "GROUP", "target_id": "<group-id>"},
    "reason": "Give the on-call group read access"
  }'

{
  "id": "areq_...",
  "workflow_id": "<workflow-id>",
  "requester_user_id": "<user-id>",
  "request_type": "attach_policy",
  "request_data": {"policy_id": "<policy-id>", "target_type": "GROUP", "target_id": "<group-id>"},
  "status": "PENDING",
  "reason": "Give the on-call group read access",
  "created_at": "2026-10-20T09:00:00Z",
  "updated_at": "2026-10-20T09:00:00Z"
}

Decide a request

POST /v1/approvals/requests/{request_id}/decisions needs iam:approval:manage.

curl -X POST https://api.hexelstudio.com/v1/approvals/requests/<request-id>/decisions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"decision": "APPROVED", "comment": "Looks good"}'

{
  "id": "ad_...",
  "request_id": "<request-id>",
  "approver_user_id": "<user-id>",
  "decision": "APPROVED",
  "comment": "Looks good",
  "decided_at": "2026-10-20T09:05:00Z"
}

The approver is the caller. A decision is accepted only when:

• the request is still PENDING (otherwise 409, approval request is no longer pending);
• the caller is not the requester (otherwise 403);
• the caller is listed in approver_user_ids, when the workflow sets it (otherwise 403);
• the caller holds approver_role, when the workflow sets it (otherwise 403). A membership level counts for that level and every higher one (org_owner > org_admin > org_member > org_viewer). A permission set counts when it is assigned to the caller, or to one of the caller's groups, for the whole organization and the assignment has not expired.

One REJECTED decision rejects the request. The request becomes APPROVED once min_approvals different approvers have approved it.

GET /v1/approvals/requests/{request_id}/decisions lists the decisions on a request and needs iam:approval:read.