List grants with filters

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