Workflows & Access Requests API

This page covers two related areas:

Workflow management — Define reusable approval workflows and manage their lifecycle. Requires workflow:read or workflow:write permission.
Access requests — Self-service requests for elevated access, routed through a configured workflow for approval. Some endpoints are available to any authenticated user; others require workflow:read or workflow:write.
Approvals — Approve or reject decisions assigned to the current user.

Base path: https://api.ithbat.io/api/v1/

Workflows

Workflows define the steps, approvers, and conditions for routing access requests through an approval process. A workflow must be active before it can be used to process new requests.

GET /api/v1/workflows

Permission: workflow:read

List all workflows defined in the tenant.

curl "https://api.ithbat.io/api/v1/workflows" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "workflows": [
      {
        "id": "wf1a2b3c-d4e5-6789-abcd-ef0123456789",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "name": "Standard Role Approval",
        "description": "Single-step manager approval for standard role assignments",
        "status": "active",
        "steps": [
          {
            "order": 1,
            "name": "Manager Approval",
            "approverType": "role",
            "approverValue": "manager",
            "timeoutHours": 48
          }
        ],
        "createdAt": "2026-01-05T09:00:00Z",
        "updatedAt": "2026-02-01T14:00:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/workflows/{id}

Permission: workflow:read

Retrieve a single workflow by ID.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the workflow

curl "https://api.ithbat.io/api/v1/workflows/wf1a2b3c-d4e5-6789-abcd-ef0123456789" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200 — Returns the full workflow object.

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Workflow does not exist in this tenant

POST /api/v1/workflows

Permission: workflow:write

Create a new workflow definition.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Unique workflow name within the tenant
`description`	string	No	Description of the workflow purpose
`steps`	array	Yes	Ordered list of approval step objects

Each step in steps:

Field	Type	Required	Description
`order`	integer	Yes	Step sequence number (1-based)
`name`	string	Yes	Display name for the step
`approverType`	string	Yes	How approvers are resolved: `user`, `role`, or `group`
`approverValue`	string	Yes	User ID, role name, or group ID depending on `approverType`
`timeoutHours`	integer	No	Hours before the step auto-escalates or expires (default: 72)

curl -X POST "https://api.ithbat.io/api/v1/workflows" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Privileged Access Approval",
    "description": "Two-step approval required for privileged role assignments",
    "steps": [
      {
        "order": 1,
        "name": "Line Manager Approval",
        "approverType": "role",
        "approverValue": "manager",
        "timeoutHours": 24
      },
      {
        "order": 2,
        "name": "Security Team Sign-off",
        "approverType": "group",
        "approverValue": "g7f6e5d4-c3b2-a190-8765-4321fedcba09",
        "timeoutHours": 48
      }
    ]
  }'

Response 201

{
  "success": true,
  "data": {
    "id": "wf9z8y7x-6w5v-4321-uvwx-yz0987654321",
    "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
    "name": "Privileged Access Approval",
    "description": "Two-step approval required for privileged role assignments",
    "status": "draft",
    "steps": [
      {
        "order": 1,
        "name": "Line Manager Approval",
        "approverType": "role",
        "approverValue": "manager",
        "timeoutHours": 24
      },
      {
        "order": 2,
        "name": "Security Team Sign-off",
        "approverType": "group",
        "approverValue": "g7f6e5d4-c3b2-a190-8765-4321fedcba09",
        "timeoutHours": 48
      }
    ],
    "createdAt": "2026-03-19T10:00:00Z",
    "updatedAt": "2026-03-19T10:00:00Z"
  }
}

Error Codes

Code	HTTP	Description
`DUPLICATE_NAME`	409	A workflow with this name already exists in the tenant
`VALIDATION_ERROR`	400	`steps` must be non-empty and step orders must be unique

PUT /api/v1/workflows/{id}

Permission: workflow:write

Update a workflow definition. Only draft workflows can be fully edited. Active workflows can only have their name and description updated; modify the steps on a draft copy instead.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the workflow to update

Request Body

Field	Type	Required	Description
`name`	string	No	Updated name
`description`	string	No	Updated description
`steps`	array	No	Updated steps (draft workflows only; replaces existing steps)

curl -X PUT "https://api.ithbat.io/api/v1/workflows/wf9z8y7x-6w5v-4321-uvwx-yz0987654321" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{"description": "Two-step approval for privileged and sensitive role assignments"}'

Response 200 — Returns the updated workflow object.

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Workflow does not exist in this tenant
`VALIDATION_ERROR`	400	Attempt to modify steps on an active workflow

DELETE /api/v1/workflows/{id}

Permission: workflow:write

Delete a workflow. Only draft or deactivated workflows with no running instances can be deleted.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the workflow to delete

curl -X DELETE "https://api.ithbat.io/api/v1/workflows/wf9z8y7x-6w5v-4321-uvwx-yz0987654321" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "Workflow deleted"
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Workflow does not exist in this tenant
`CONFLICT`	409	Workflow has active instances and cannot be deleted

POST /api/v1/workflows/{id}/activate

Permission: workflow:write

Activate a draft or deactivated workflow, making it available for new access requests.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the workflow to activate

curl -X POST "https://api.ithbat.io/api/v1/workflows/wf9z8y7x-6w5v-4321-uvwx-yz0987654321/activate" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "id": "wf9z8y7x-6w5v-4321-uvwx-yz0987654321",
    "status": "active",
    "updatedAt": "2026-03-19T11:00:00Z"
  }
}

POST /api/v1/workflows/{id}/deactivate

Permission: workflow:write

Deactivate an active workflow. In-progress instances continue to completion; no new instances can be started.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the workflow to deactivate

curl -X POST "https://api.ithbat.io/api/v1/workflows/wf9z8y7x-6w5v-4321-uvwx-yz0987654321/deactivate" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "id": "wf9z8y7x-6w5v-4321-uvwx-yz0987654321",
    "status": "inactive",
    "updatedAt": "2026-03-19T11:30:00Z"
  }
}

POST /api/v1/workflows/{id}/start

Permission: workflow:write

Manually start a new workflow instance outside of the access request flow. Useful for administrative or programmatic triggers.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the workflow to start

Request Body

Field	Type	Required	Description
`subject`	object	Yes	Context describing what or who triggered the workflow
`metadata`	object	No	Additional key-value data attached to this instance

curl -X POST "https://api.ithbat.io/api/v1/workflows/wf1a2b3c-d4e5-6789-abcd-ef0123456789/start" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "reason": "Temporary elevated access for incident response"
    },
    "metadata": {
      "incidentId": "INC-20260319-001"
    }
  }'

Response 201

{
  "success": true,
  "data": {
    "instanceId": "wi5a6b7c8-d9e0-1234-abcd-ef5678901234",
    "workflowId": "wf1a2b3c-d4e5-6789-abcd-ef0123456789",
    "status": "pending",
    "currentStep": 1,
    "createdAt": "2026-03-19T12:00:00Z"
  }
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Workflow does not exist
`VALIDATION_ERROR`	400	Workflow is not in `active` status

Workflow Instances

A workflow instance represents a single running execution of a workflow definition.

GET /api/v1/workflow-instances

Permission: workflow:read

List all workflow instances in the tenant.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	25	Results per page (max 100)
`workflowId`	string	—	Filter by workflow ID
`status`	string	—	Filter by status: `pending`, `approved`, `rejected`, `cancelled`

curl "https://api.ithbat.io/api/v1/workflow-instances?status=pending&limit=25" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "instances": [
      {
        "id": "wi5a6b7c8-d9e0-1234-abcd-ef5678901234",
        "workflowId": "wf1a2b3c-d4e5-6789-abcd-ef0123456789",
        "workflowName": "Standard Role Approval",
        "status": "pending",
        "currentStep": 1,
        "createdAt": "2026-03-19T12:00:00Z",
        "updatedAt": "2026-03-19T12:00:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/workflow-instances/{id}

Permission: workflow:read

Get a single workflow instance by ID.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the workflow instance

curl "https://api.ithbat.io/api/v1/workflow-instances/wi5a6b7c8-d9e0-1234-abcd-ef5678901234" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "id": "wi5a6b7c8-d9e0-1234-abcd-ef5678901234",
    "workflowId": "wf1a2b3c-d4e5-6789-abcd-ef0123456789",
    "workflowName": "Standard Role Approval",
    "status": "pending",
    "currentStep": 1,
    "totalSteps": 1,
    "subject": {
      "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "reason": "Need read access to audit logs for compliance report"
    },
    "metadata": {},
    "createdAt": "2026-03-19T12:00:00Z",
    "updatedAt": "2026-03-19T12:00:00Z"
  }
}

GET /api/v1/workflow-instances/{id}/executions

Permission: workflow:read

Get the full execution history for a workflow instance — all approval decisions, step transitions, and system events.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the workflow instance

curl "https://api.ithbat.io/api/v1/workflow-instances/wi5a6b7c8-d9e0-1234-abcd-ef5678901234/executions" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "instanceId": "wi5a6b7c8-d9e0-1234-abcd-ef5678901234",
    "executions": [
      {
        "id": "ex1a2b3c-d4e5-6789-abcd-ef0123456789",
        "step": 1,
        "stepName": "Manager Approval",
        "event": "step_started",
        "actorId": null,
        "note": null,
        "occurredAt": "2026-03-19T12:00:00Z"
      },
      {
        "id": "ex2b3c4d-e5f6-7890-bcde-f01234567890",
        "step": 1,
        "stepName": "Manager Approval",
        "event": "approved",
        "actorId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
        "note": "Approved for the duration of the compliance window",
        "occurredAt": "2026-03-19T14:23:00Z"
      }
    ]
  }
}

POST /api/v1/workflow-instances/{id}/cancel

Permission: workflow:write

Cancel a running workflow instance. In-flight approval tasks are closed and no further transitions occur.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the workflow instance to cancel

Request Body

Field	Type	Required	Description
`reason`	string	No	Reason for cancellation

curl -X POST "https://api.ithbat.io/api/v1/workflow-instances/wi5a6b7c8-d9e0-1234-abcd-ef5678901234/cancel" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Request submitted in error"}'

Response 200

{
  "success": true,
  "message": "Workflow instance cancelled"
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Instance does not exist
`CONFLICT`	409	Instance is already in a terminal state (`approved`, `rejected`, `cancelled`)

Access Requests

Access requests allow users to self-service request access to roles, groups, or resources. Each request is routed through a configured workflow for approval.

POST /api/v1/access-requests

Authentication required. Self-service — any authenticated user.

Submit a new access request. The tenant must have an active workflow configured for the requested resource type.

Request Body

Field	Type	Required	Description
`resourceType`	string	Yes	Type of access being requested: `role`, `group`, or `resource`
`resourceId`	string	Yes	ID of the role, group, or resource being requested
`justification`	string	Yes	Business justification for the request
`duration`	object	No	Requested access duration (`value` integer + `unit` string: `hours`, `days`)

curl -X POST "https://api.ithbat.io/api/v1/access-requests" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "role",
    "resourceId": "r1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "justification": "Need admin access to complete the Q1 compliance audit",
    "duration": {
      "value": 5,
      "unit": "days"
    }
  }'

Response 201

{
  "success": true,
  "data": {
    "id": "ar3c4d5e-f6a7-8901-cdef-012345678901",
    "requesterId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resourceType": "role",
    "resourceId": "r1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resourceName": "Audit Admin",
    "justification": "Need admin access to complete the Q1 compliance audit",
    "status": "pending",
    "workflowInstanceId": "wi5a6b7c8-d9e0-1234-abcd-ef5678901234",
    "duration": {
      "value": 5,
      "unit": "days"
    },
    "createdAt": "2026-03-19T13:00:00Z",
    "updatedAt": "2026-03-19T13:00:00Z"
  }
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	The requested role, group, or resource does not exist
`CONFLICT`	409	User already has a pending request for this resource
`VALIDATION_ERROR`	400	No active workflow is configured for this resource type

GET /api/v1/access-requests/my-requests

Authentication required. Self-service — returns only the current user's requests.

List all access requests submitted by the authenticated user.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	25	Results per page (max 100)
`status`	string	—	Filter by status: `pending`, `approved`, `rejected`, `cancelled`

curl "https://api.ithbat.io/api/v1/access-requests/my-requests?status=pending" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "requests": [
      {
        "id": "ar3c4d5e-f6a7-8901-cdef-012345678901",
        "resourceType": "role",
        "resourceId": "r1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "resourceName": "Audit Admin",
        "justification": "Need admin access to complete the Q1 compliance audit",
        "status": "pending",
        "createdAt": "2026-03-19T13:00:00Z",
        "updatedAt": "2026-03-19T13:00:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/access-requests

Permission: workflow:read

List all access requests in the tenant across all users.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	25	Results per page (max 100)
`status`	string	—	Filter by status
`requesterId`	string	—	Filter by the requesting user's ID
`resourceType`	string	—	Filter by resource type: `role`, `group`, `resource`

curl "https://api.ithbat.io/api/v1/access-requests?status=pending&limit=50" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200 — Same structure as GET /access-requests/my-requests but includes all users' requests.

GET /api/v1/access-requests/{id}

Permission: workflow:read

Retrieve a single access request by ID.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the access request

curl "https://api.ithbat.io/api/v1/access-requests/ar3c4d5e-f6a7-8901-cdef-012345678901" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "id": "ar3c4d5e-f6a7-8901-cdef-012345678901",
    "requesterId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "requesterName": "Alice Smith",
    "requesterEmail": "[email protected]",
    "resourceType": "role",
    "resourceId": "r1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resourceName": "Audit Admin",
    "justification": "Need admin access to complete the Q1 compliance audit",
    "status": "pending",
    "workflowInstanceId": "wi5a6b7c8-d9e0-1234-abcd-ef5678901234",
    "duration": {
      "value": 5,
      "unit": "days"
    },
    "createdAt": "2026-03-19T13:00:00Z",
    "updatedAt": "2026-03-19T13:00:00Z"
  }
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Access request does not exist in this tenant

GET /api/v1/access-requests/pending-approvals

Permission: workflow:read

List all access requests across the tenant that are currently awaiting an approval decision.

curl "https://api.ithbat.io/api/v1/access-requests/pending-approvals" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "requests": [
      {
        "id": "ar3c4d5e-f6a7-8901-cdef-012345678901",
        "requesterName": "Alice Smith",
        "requesterEmail": "[email protected]",
        "resourceType": "role",
        "resourceName": "Audit Admin",
        "justification": "Need admin access to complete the Q1 compliance audit",
        "status": "pending",
        "currentStep": 1,
        "currentStepName": "Manager Approval",
        "createdAt": "2026-03-19T13:00:00Z"
      }
    ],
    "total": 1
  }
}

POST /api/v1/access-requests/{id}/approve

Permission: workflow:write

Approve an access request administratively, bypassing the normal workflow step assignment. The workflow instance advances or completes immediately.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the access request

Request Body

Field	Type	Required	Description
`note`	string	No	Optional approval note visible to the requester

curl -X POST "https://api.ithbat.io/api/v1/access-requests/ar3c4d5e-f6a7-8901-cdef-012345678901/approve" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{"note": "Approved for Q1 compliance audit window. Access expires 2026-03-24."}'

Response 200

{
  "success": true,
  "message": "Access request approved"
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Access request does not exist
`CONFLICT`	409	Request is not in a `pending` state

POST /api/v1/access-requests/{id}/reject

Permission: workflow:write

Reject an access request administratively.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the access request

Request Body

Field	Type	Required	Description
`reason`	string	Yes	Reason for rejection, visible to the requester

curl -X POST "https://api.ithbat.io/api/v1/access-requests/ar3c4d5e-f6a7-8901-cdef-012345678901/reject" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{"reason": "This level of access is not appropriate for your current role. Please request group-level access instead."}'

Response 200

{
  "success": true,
  "message": "Access request rejected"
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Access request does not exist
`CONFLICT`	409	Request is not in a `pending` state
`VALIDATION_ERROR`	400	`reason` is required when rejecting

POST /api/v1/access-requests/{id}/cancel

Permission: workflow:write

Cancel a pending access request. The associated workflow instance is also cancelled.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the access request

Request Body

Field	Type	Required	Description
`reason`	string	No	Optional cancellation reason

curl -X POST "https://api.ithbat.io/api/v1/access-requests/ar3c4d5e-f6a7-8901-cdef-012345678901/cancel" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{"reason": "No longer needed — resolved through a different process"}'

Response 200

{
  "success": true,
  "message": "Access request cancelled"
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Access request does not exist
`CONFLICT`	409	Request is already in a terminal state

Approvals

Approval endpoints let the currently authenticated user act on approval tasks that have been assigned to them through a workflow step.

GET /api/v1/approvals/pending

Authentication required. Self-service — returns only approvals assigned to the current user.

List all pending approval tasks assigned to the authenticated user.

curl "https://api.ithbat.io/api/v1/approvals/pending" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "approvals": [
      {
        "id": "ap7d8e9f-a0b1-2345-cdef-678901234567",
        "accessRequestId": "ar3c4d5e-f6a7-8901-cdef-012345678901",
        "workflowInstanceId": "wi5a6b7c8-d9e0-1234-abcd-ef5678901234",
        "step": 1,
        "stepName": "Manager Approval",
        "requesterName": "Alice Smith",
        "requesterEmail": "[email protected]",
        "resourceType": "role",
        "resourceName": "Audit Admin",
        "justification": "Need admin access to complete the Q1 compliance audit",
        "requestedAt": "2026-03-19T13:00:00Z",
        "expiresAt": "2026-03-21T13:00:00Z"
      }
    ],
    "total": 1
  }
}

POST /api/v1/approvals/{id}/decide

Authentication required. Self-service — the authenticated user must be the assigned approver for this task.

Submit an approval decision (approve or reject) for a task assigned to the current user.

Path Parameters

Parameter	Type	Description
`id`	string	UUID of the approval task

Request Body

Field	Type	Required	Description
`decision`	string	Yes	`approve` or `reject`
`note`	string	No	Optional comment visible to the requester and recorded in the audit log

curl -X POST "https://api.ithbat.io/api/v1/approvals/ap7d8e9f-a0b1-2345-cdef-678901234567/decide" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve",
    "note": "Verified with compliance team. Approved for audit duration only."
  }'

Response 200

{
  "success": true,
  "data": {
    "approvalId": "ap7d8e9f-a0b1-2345-cdef-678901234567",
    "decision": "approve",
    "accessRequestStatus": "approved",
    "decidedAt": "2026-03-19T15:10:00Z"
  }
}

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	Approval task does not exist or is not assigned to the current user
`CONFLICT`	409	A decision has already been recorded for this approval task
`VALIDATION_ERROR`	400	`decision` must be `approve` or `reject`

Workflows​

GET /api/v1/workflows​

GET /api/v1/workflows/{id}​

POST /api/v1/workflows​

PUT /api/v1/workflows/{id}​

DELETE /api/v1/workflows/{id}​

POST /api/v1/workflows/{id}/activate​

POST /api/v1/workflows/{id}/deactivate​

POST /api/v1/workflows/{id}/start​

Workflow Instances​

GET /api/v1/workflow-instances​

GET /api/v1/workflow-instances/{id}​

GET /api/v1/workflow-instances/{id}/executions​

POST /api/v1/workflow-instances/{id}/cancel​

Access Requests​

POST /api/v1/access-requests​

GET /api/v1/access-requests/my-requests​

GET /api/v1/access-requests​

GET /api/v1/access-requests/{id}​

GET /api/v1/access-requests/pending-approvals​

POST /api/v1/access-requests/{id}/approve​

POST /api/v1/access-requests/{id}/reject​

POST /api/v1/access-requests/{id}/cancel​

Approvals​

GET /api/v1/approvals/pending​

POST /api/v1/approvals/{id}/decide​

Workflows

GET /api/v1/workflows

GET /api/v1/workflows/{id}

POST /api/v1/workflows

PUT /api/v1/workflows/{id}

DELETE /api/v1/workflows/{id}

POST /api/v1/workflows/{id}/activate

POST /api/v1/workflows/{id}/deactivate

POST /api/v1/workflows/{id}/start

Workflow Instances

GET /api/v1/workflow-instances

GET /api/v1/workflow-instances/{id}

GET /api/v1/workflow-instances/{id}/executions

POST /api/v1/workflow-instances/{id}/cancel

Access Requests

POST /api/v1/access-requests

GET /api/v1/access-requests/my-requests

GET /api/v1/access-requests

GET /api/v1/access-requests/{id}

GET /api/v1/access-requests/pending-approvals

POST /api/v1/access-requests/{id}/approve

POST /api/v1/access-requests/{id}/reject

POST /api/v1/access-requests/{id}/cancel

Approvals

GET /api/v1/approvals/pending

POST /api/v1/approvals/{id}/decide