Workspace-scoped REST API for the Atomicwork agentic service management platform: requests/tickets, changes, problems, assets, users, workspaces, service catalog, workflows, custom objects, audit logs, and IGA access grants. OpenAPI 3.1, API-key auth (X-Api-Key + X-Workspace-Id).
openapi: 3.1.0
info:
title: Atomicwork Public API
version: 1.0.0
paths:
/api/v1/iga/grants:
post:
operationId: postapi-v-1-iga-grants
summary: Create a grant for a user
description: >
Create an identity grant directly without going through the IGA approval workflow. This is the primary endpoint
for programmatic access provisioning — use it when an external system (HRMS, onboarding tool, compliance
platform) needs to grant access to a user.
**Required fields:** `user_id` and `entitlement_id`. Call `GET /iga/apps` then `GET
/iga/entitlements?app_id={id}` to discover valid entitlement IDs.
**Optional fields:**
- `policy_id` or `policy_key` — link the grant to a specific access policy
- `granted_by` — record which user or system initiated the grant
- `granted_at` — backdate the grant timestamp (ISO 8601); defaults to now
The grant method (how provisioning happens) is automatically derived from the entitlement's provisioning
configuration — Okta, Azure AD, JumpCloud, Google Workspace, or manual service request.
Returns the created grant with its `id`, resolved `status`, `entitlement`, `app`, and provisioning details.
tags:
- accessManagement
parameters:
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Access Management_postapi_v1_iga_grants_Response_200'
requestBody:
description: Request body for creating a grant via the public API
content:
application/json:
schema:
type: object
properties:
user_id:
type: integer
format: int64
description: The ID of the user who will receive the grant
entitlement_id:
type: integer
format: int64
description: The ID of the entitlement to grant
policy_id:
type: integer
format: int64
description: Optional policy ID to associate with the grant
policy_key:
type: string
description: Optional policy key (alternative to policy_id)
granted_by:
type: integer
format: int64
description: Optional user ID of who authorized this grant. Defaults to the API key owner.
granted_at:
type: string
format: date-time
description: Optional timestamp of when the grant was authorized. Defaults to current time.
required:
- user_id
- entitlement_id
/api/v1/iga/grants/list:
post:
operationId: postapi-v-1-iga-grants-list
summary: List grants with filters
description: >
Search and list identity grants with advanced filtering. This is the primary query endpoint for building
compliance dashboards, access reviews, and audit reports.
Supports filtering by user, app, entitlement, status, and date ranges via request body filters. Combine multiple
filters for precise queries — for example, find all active grants for a specific app that were created in the
last 90 days.
Use query parameters for quick filtering (`app_id`, `policy_id`, `sort_order`) or the request body for
structured filter objects with operators like `IS_ANY_OF`, `IS_BETWEEN`, etc.
**Pagination:** Returns paginated results with `page`, `per_page` (default 25), and `next_page_token` for
cursor-based pagination. Pass `next_page_token` from the previous response to fetch the next page.
**Response** includes full grant details: user info, entitlement, app, policy, provisioning status, revocation
status, and timestamps.
### Filtering
The request body is an **array of filter objects**. Send an empty array (`[]`) to retrieve all records.
Each filter object has the following fields:
| Field | Type | Description |
|---|---|---|
| `attribute` | string | The field to filter on (see Supported attributes below) |
| `operator` | string | Comparison operator (see Available operators below) |
| `values` | array | One or more `{ "value": <scalar> }` objects |
**Supported attributes**
| Attribute | Typical operator | Description |
|---|---|---|
| `status` | `IS_ANY_OF` | Grant status **bucket** (not the raw status). Accepted values: `ACTIVE` (includes
GRANTED and EXTENDED grants), `INACTIVE` (includes REVOKED and EXPIRED grants), `REVOKED` (revoked only). See
the Status Reference table below. |
| `user` | `IS_ANY_OF` | Numeric user ID of the grant recipient (the `id` field from `GET /api/v1/users`). Pass
one or more user IDs to filter grants belonging to specific people. |
| `app` | `IS_ANY_OF` | Application ID — the identity resource app the entitlement belongs to (the `id` field
from `GET /api/v1/iga/apps`). Filters grants to entitlements under a specific app. |
| `entitlement` | `IS_ANY_OF` | Entitlement ID — the specific entitlement (group, role, license, etc.) the grant
was issued for. Use `GET /api/v1/iga/entitlements` to discover IDs. |
| `entitlement_value` | `IS_ANY_OF` | Entitlement value string — filters by the human-readable entitlement value
(e.g. the group name or role name) rather than the numeric ID. |
| `granted_at` | `IS_BETWEEN` | Grant creation timestamp. Requires exactly **two** values: `[start, end]` (both
inclusive). Accepts ISO 8601 format (`2024-01-01T00:00:00Z`). |
| `expires_at` | `IS_BETWEEN` | Grant expiration timestamp. Same format as `granted_at`. Use this to find grants
expiring within a specific window. |
| `last_login_at` | `IS_BETWEEN` | Last login timestamp for the grant recipient. Same format as `granted_at`.
Useful for identifying unused grants where the user hasn't logged in recently. |
**Available operators**
| Operator | Meaning |
|---|---|
| `EQUALS` | Exact match |
| `NOT_EQUALS` | Exclude exact match |
| `IN` / `IS_ANY_OF` | Match any value in the list |
| `IS_NOT_ANY_OF` | Exclude all listed values |
| `IS_BETWEEN` | Inclusive range — pass exactly two values: `[start, end]` |
| `IS_ON_OR_BEFORE` / `IS_ON_OR_AFTER` | Date/time boundary comparisons |
| `CONTAINS` / `TEXT_CONTAINS` | Substring or set membership |
| `IS_NULL` / `IS_NOT_NULL` | Null checks — `values` array can be empty |
| `STARTS_WITH` / `ENDS_WITH` | String prefix/suffix match |
**Status Reference**
Grants have a raw status and a **status bucket** used for filtering:
| Filter value | Raw statuses included | Description |
|---|---|---|
| `ACTIVE` | GRANTED, EXTENDED | Currently valid grants |
| `INACTIVE` | REVOKED, EXPIRED | No longer valid grants |
| `REVOKED` | REVOKED | Only manually or system-revoked grants |
**Grant types** (returned in responses, not used as filter attributes)
| Type | Description |
|---|---|
| `BIRTHRIGHT` | Automatically assigned based on user attributes (department, role, etc.) |
| `PREAPPROVED` | Pre-approved via an access policy — no approval workflow required |
| `APPROVED` | Granted after completing an approval workflow |
**Entitlement types** (filter via the entitlements endpoint, not on grants directly)
| Type | Description |
|---|---|
| `GROUP` | Identity provider group membership (e.g. Azure AD group, Okta group) |
| `ROLE` | Application role assignment |
| `LICENSE` | Software license entitlement |
| `REPO` | Repository access |
| `OTHER` | Custom entitlement type |
**Provisioning providers** (shown in grant responses)
| Provider | Description |
|---|---|
| `OKTA` | Okta identity provider |
| `AZURE_AD` | Microsoft Entra ID (Azure AD) |
| `JUMPCLOUD` | JumpCloud directory |
| `GOOGLE_WORKSPACE` | Google Workspace |
| `MS_INTUNE` | Microsoft Intune device management |
| `MANUAL` | Manual provisioning (service request created for IT team) |
**Example**
```json
[
{
"attribute": "status",
"operator": "IS_ANY_OF",
"values": [
{
"value": "ACTIVE"
}
]
},
{
"attribute": "app",
"operator": "IS_ANY_OF",
"values": [
{
"value": 42
}
]
},
{
"attribute": "granted_at",
"operator": "IS_BETWEEN",
"values": [
{
"value": "2024-01-01T00:00:00Z"
},
{
"value": "2024-12-31T23:59:59Z"
}
]
},
{
"attribute": "user",
"operator": "IS_ANY_OF",
"values": [
{
"value": 123
},
{
"value": 456
}
]
}
]
```
tags:
- accessManagement
parameters:
- name: search_key
in: query
description: Free-text search across grant, entitlement, and user fields.
required: false
schema:
type: string
- name: sort_order
in: query
description: >-
Sort order for results. Common values: GRANTED_AT_DESC (newest first), GRANTED_AT_ASC (oldest first),
EXPIRES_AT_ASC (expiring soonest first).
required: false
schema:
$ref: '#/components/schemas/ApiV1IgaGrantsListPostParametersSortOrder'
- name: policy_id
in: query
description: Filter grants linked to a specific access policy by its UUID key.
required: false
schema:
type: string
- name: app_id
in: query
description: Filter grants to entitlements under a specific app (from GET /iga/apps).
required: false
schema:
type: integer
format: int64
- name: page
in: query
description: Page number (1-indexed). Default 1.
required: false
schema:
type: integer
default: 1
- name: per_page
in: query
description: Results per page (default 25, max 100).
required: false
schema:
type: integer
default: 25
- name: next_page_token
in: query
description: >-
Token from previous response to fetch the next page. When provided, takes priority over page and per_page
parameters.
required: false
schema:
type: string
- name: ids
in: query
description: Comma-separated list of grant IDs to filter by. When provided, returns only grants matching these IDs.
required: false
schema:
type: string
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Access Management_postapi_v1_iga_grants_list_Response_200'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiV1IgaGrantsListPostRequestBodyContentApplicationJsonSchemaItems'
/api/v1/iga/grants/{grant_id}:
put:
operationId: putapi-v-1-iga-grants-grant-id
summary: Update a grant
description: >
Update an identity grant's metadata. Use this to change the associated policy, update the grantor, or adjust
grant timestamps.
**Updatable fields:**
- `status` — transition the grant to a new status
- `policy_id` or `policy_key` — reassign the grant to a different access policy
- `granted_by` — update the grantor identifier
- `granted_at` — correct the grant timestamp
To revoke a grant, use the dedicated `POST /iga/grants/{grant_id}/revoke` endpoint instead — it handles
deprovisioning workflows.
tags:
- accessManagement
parameters:
- name: grant_id
in: path
description: ''
required: true
schema:
type: string
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Access Management_putapi_v1_iga_grants__grant_id_Response_200'
requestBody:
description: Request body for updating a grant via the public API
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/ApiV1IgaGrantsGrantIdPutRequestBodyContentApplicationJsonSchemaStatus'
policy_id:
type: integer
format: int64
description: Change the policy associated with the grant
policy_key:
type: string
description: Change the policy by key (alternative to policy_id)
granted_by:
type: integer
format: int64
description: User ID who authorized this grant
granted_at:
type: string
format: date-time
description: When the grant was authorized
/api/v1/iga/grants/{grant_id}/revoke:
post:
operationId: postapi-v-1-iga-grants-grant-id-revoke
summary: Revoke a grant
description: >
Revoke an identity grant. Supports two modes depending on whether you want the identity provider to be notified:
**Immediate revocation (default):** With `skip_deprovisioning=true` (the default), the grant is marked as
`REVOKED` immediately in Atomicwork. No action is taken in the identity provider — use this when you've already
removed access externally or when the grant is informational only.
**Full deprovisioning:** With `skip_deprovisioning=false`, Atomicwork triggers the full deprovisioning workflow.
Depending on the entitlement's provisioning config, this may:
- Remove the user from an Azure AD or Okta group
- Remove a JumpCloud or Google Workspace assignment
- Create a manual service request for IT to action
The response includes a `revocation_status` object with `status` (IN_PROGRESS, COMPLETED, or FAILED) and a
`schedule_id` you can use to track the deprovisioning execution.
**Optional fields:**
- `reason` — free-text reason for the revocation (recorded in grant history)
tags:
- accessManagement
parameters:
- name: grant_id
in: path
description: The grant ID to revoke
required: true
schema:
type: integer
format: int64
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Access Management_postapi_v1_iga_grants__grant_id__revoke_Response_200'
requestBody:
description: Request body for revoking a grant via the public API
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: Optional reason for revoking the grant
skip_deprovisioning:
type: boolean
default: true
description: >
When true (default), marks the grant as REVOKED immediately without triggering IDP deprovisioning.
When false, triggers the full deprovisioning workflow (Azure AD/Okta group removal or service
request creation).
/api/v1/iga/grants/{grant_id}/history:
get:
operationId: getapi-v-1-iga-grants-grant-id-history
summary: Get grant history
description: >
Retrieve the complete audit trail for a specific grant. Returns a paginated timeline of all lifecycle events —
creation, extensions, revocations, and expirations — with timestamps and actors.
Each history entry includes:
- `event_type` — one of `GRANTED`, `EXTENDED`, `REVOKED`, or `EXPIRED`
- `event_at` — when the event occurred (ISO 8601)
- `event_by` — who or what triggered the event
**Pagination:** Supports `page`, `per_page`, and `sort_order` (CREATED_AT_ASC or CREATED_AT_DESC). Default sort
is newest first.
tags:
- accessManagement
parameters:
- name: grant_id
in: path
description: The unique identifier of the grant
required: true
schema:
type: integer
format: int64
- name: page
in: query
description: ''
required: false
schema:
type: integer
default: 1
- name: per_page
in: query
description: ''
required: false
schema:
type: integer
default: 25
- name: sort_order
in: query
description: Sort order for grant history results
required: false
schema:
$ref: '#/components/schemas/ApiV1IgaGrantsGrantIdHistoryGetParametersSortOrder'
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Access Management_getapi_v1_iga_grants__grant_id__history_Response_200'
/api/v1/iga/apps:
get:
operationId: getapi-v-1-iga-apps
summary: List available apps
description: >
List the identity resource apps connected to your workspace. This is the starting point for grant discovery —
each app represents a connected identity provider (Okta, Azure AD, JumpCloud, Google Workspace, etc.) and
contains entitlements that can be granted to users.
**Typical flow:** Call this endpoint first to get `app_id` values, then call `GET /iga/entitlements?app_id={id}`
to browse the entitlements (groups, roles, licenses) available in each app.
**Pagination:** Supports `page` and `per_page` (default 25). Use `search_key` to filter apps by name.
tags:
- accessManagement
parameters:
- name: search_key
in: query
description: Filter apps by name (partial match).
required: false
schema:
type: string
- name: page
in: query
description: Page number (1-indexed). Default 1.
required: false
schema:
type: integer
default: 1
- name: per_page
in: query
description: Results per page (default 25).
required: false
schema:
type: integer
default: 25
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Access Management_getapi_v1_iga_apps_Response_200'
/api/v1/iga/entitlements:
get:
operationId: getapi-v-1-iga-entitlements
summary: List available entitlements
description: >
List the entitlements (groups, roles, licenses, repos) available for granting. Each entitlement belongs to an
app and represents a specific access right that can be assigned to a user.
**Filter by app:** Pass `app_id` (from `GET /iga/apps`) to list only entitlements under a specific identity
provider app.
**Filter by type:** Use the `type` parameter to narrow by entitlement category:
- `GROUP` — identity provider group membership (e.g. Azure AD security group, Okta group)
- `ROLE` — application role assignment
**Filter by status:** Use `status` to filter by publication state:
- `PUBLISHED` — available for granting
- `DRAFT` — not yet available
**Pagination:** Supports `page`, `per_page` (default 25), and `search_key` for name search.
tags:
- accessManagement
parameters:
- name: search_key
in: query
description: Filter entitlements by name (partial match).
required: false
schema:
type: string
- name: app_id
in: query
description: Filter entitlements under a specific app (from GET /iga/apps).
required: false
schema:
type: integer
format: int64
- name: type
in: query
description: 'Filter by entitlement category: GROUP (IDP group membership), ROLE (application role).'
required: false
schema:
$ref: '#/components/schemas/ApiV1IgaEntitlementsGetParametersType'
- name: status
in: query
description: 'Filter by publication state: PUBLISHED (available for granting), DRAFT (not yet available).'
required: false
schema:
$ref: '#/components/schemas/ApiV1IgaEntitlementsGetParametersStatus'
- name: page
in: query
description: Page number (1-indexed). Default 1.
required: false
schema:
type: integer
default: 1
- name: per_page
in: query
description: Results per page (default 25).
required: false
schema:
type: integer
default: 25
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Access Management_getapi_v1_iga_entitlements_Response_200'
post:
operationId: postapi-v-1-iga-entitlements
summary: Create an entitlement
description: |
Create a new identity entitlement. Requires app_id and type.
The entitlement can then be associated with policies and granted to users.
tags:
- accessManagement
parameters:
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Access Management_postapi_v1_iga_entitlements_Response_200'
requestBody:
description: Request body for creating an entitlement via the public API
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the entitlement
description:
type: string
description: Description of the entitlement
app_id:
type: integer
format: int64
description: ID of the identity resource app this entitlement belongs to
status:
$ref: '#/components/schemas/ApiV1IgaEntitlementsPostRequestBodyContentApplicationJsonSchemaStatus'
description: Status of the entitlement. Defaults to PUBLISHED if not specified.
provisioning_config:
$ref: >-
#/components/schemas/ApiV1IgaEntitlementsPostRequestBodyContentApplicationJsonSchemaProvisioningConfig
deprovisioning_config:
$ref: >-
#/components/schemas/ApiV1IgaEntitlementsPostRequestBodyContentApplicationJsonSchemaDeprovisioningConfig
required:
- name
- app_id
/api/v1/iga/policies:
post:
operationId: postapi-v-1-iga-policies
summary: Create a policy
description: |
Create a new identity policy. Requires name, type, and status.
Policies define access rules and can be associated with entitlements.
tags:
- accessManagement
parameters:
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Access Management_postapi_v1_iga_policies_Response_200'
requestBody:
description: Request body for creating an identity policy via the public API
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the policy
description:
type: string
description: Description of the policy
type:
$ref: '#/components/schemas/ApiV1IgaPoliciesPostRequestBodyContentApplicationJsonSchemaType'
condition:
$ref: '#/components/schemas/ApiV1IgaPoliciesPostRequestBodyContentApplicationJsonSchemaCondition'
approvals:
$ref: '#/components/schemas/ApiV1IgaPoliciesPostRequestBodyContentApplicationJsonSchemaApprovals'
lifecycle:
$ref: '#/components/schemas/ApiV1IgaPoliciesPostRequestBodyContentApplicationJsonSchemaLifecycle'
status:
$ref: '#/components/schemas/ApiV1IgaPoliciesPostRequestBodyContentApplicationJsonSchemaStatus'
is_active:
type: boolean
description: Whether the policy is active
entitlements:
type: array
items:
type: integer
format: int64
description: List of entitlement IDs to associate with this policy
app_id:
type: integer
format: int64
description: ID of the identity resource app this policy belongs to
is_business_justification_required:
type: boolean
description: Whether business justification is required for requests under this policy
required:
- name
- type
- status
- app_id
/api/v1/workspaces/{workspace_id}/agent-groups:
get:
operationId: getapi-v-1-workspaces-workspace-id-agent-groups
summary: Get workspace agent groups
tags:
- agentGroups
parameters:
- name: workspace_id
in: path
description: Workspace ID (numeric). Find yours under Settings → Workspace.
required: true
schema:
type: integer
format: int64
- name: search_key
in: query
description: ''
required: false
schema:
type: string
- name: page
in: query
description: ''
required: true
schema:
type: integer
default: 1
- name: per_page
in: query
description: ''
required: false
schema:
type: integer
default: 25
- name: type
in: query
description: Automation entity type (see allowed values in the enum schema).
required: false
schema:
$ref: '#/components/schemas/ApiV1WorkspacesWorkspaceIdAgentGroupsGetParametersType'
- name: X-Api-Key
in: header
required: true
schema:
type: string
- name: X-Workspace-Id
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Agent Groups_getapi_v1_workspaces__workspace_id__agent_groups_Response_200'
/api/v1/workspaces/{workspace_id}/agent-groups/{agent_group_id}/members:
get:
operationId: getapi-v-1-workspaces-workspace-id-agent-groups-agent-group-id-members
summary: Get workspace agent group members
tags:
- agentGroups
parameters:
- name: workspace_id
in: path
description: Workspace ID (numeric). Find yours under Settings → Workspace.
required: true
schema:
type: integer
format: int64
- name: agent_group_id
in: path
description: ''
required: true
schema:
type: integer
format: int64
- name: search_key
in: query
description: ''
required: false
schema:
type: string
- name: page
in: query
description: ''
required: true
schema:
type: integer
default: 1
- name: per_page
in: query
description: ''
required: false
schema:
type: integer
default: 25
- name: sort_order
in: query
description: ''
required: false
schema:
$ref: '#/components/schemas/ApiV1WorkspacesWorkspaceIdAgentGroupsAgentGroupIdMembersGetParametersSortOrder'
- name: filter
in: query
description: ''
required: false
# --- truncated at 32 KB (690 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atomicwork/refs/heads/main/openapi/atomicwork-public-api-openapi.yaml