List grants with filters | Atomicwork

curl -X POST "https://{tenant}.atomicwork.com/api/v1/iga/grants/list?sort_order=CREATED_AT_ASC" \
     -H "X-Workspace-Id: {{workspace_id}}" \
     -H "X-Api-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '[
  {
    "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
      }
    ]
  }
]'

Search and list identity grants with advanced filtering. Supports filtering by user, app, entitlement, status, and date ranges via request body filters.

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
      }
    ]
  }
]

Authentication

X-Api-Keystring

API Key authentication via header

Query parameters

search_keystringOptional>=1 character

sort_orderenumOptional

policy_idstringOptional

app_idlongOptional

pageintegerOptionalDefaults to 1

per_pageintegerOptionalDefaults to 25

next_page_tokenstringOptional

Token from previous response to fetch the next page. When provided, takes priority over page and per_page parameters.

idsstringOptional

Comma-separated list of grant IDs to filter by. When provided, returns only grants matching these IDs.

Request

This endpoint expects a list of objects.

attributestringOptional

operatorenumOptional

valueslist of objectsOptional

Response

Successful response

Filtering

Authentication

Headers

Query parameters

Request

Response