List grants with filters
POST https://{tenant}.atomicwork.com/api/v1/iga/grants/list
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
[
{
"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
}
]
}
]Authorization
X-Api-KeyrequiredAPI key authentication.
Headers
X-Workspace-IdQuery Parameters
search_keyFree-text search across grant, entitlement, and user fields.
sort_orderSort order for results. Common values: GRANTED_AT_DESC (newest first), GRANTED_AT_ASC (oldest first), EXPIRES_AT_ASC (expiring soonest first).
CREATED_AT_ASCCREATED_AT_DESCUPDATED_AT_ASCUPDATED_AT_DESCNAME_ASCNAME_DESCPUBLISHED_DESCUNPUBLISHED_DESCEXPIRES_AT_ASCEXPIRES_AT_DESCGRANTED_AT_ASCGRANTED_AT_DESCpolicy_idFilter grants linked to a specific access policy by its UUID key.
app_idFilter grants to entitlements under a specific app (from GET /iga/apps).
pagePage number (1-indexed). Default 1.
per_pageResults per page (default 25, max 100).
next_page_tokenToken from previous response to fetch the next page. When provided, takes priority over page and per_page parameters.
idsComma-separated list of grant IDs to filter by. When provided, returns only grants matching these IDs.
Response
Successful response