---
title: "List grants with filters"
method: POST
path: "/api/v1/iga/grants/list"
tags: ["accessManagement"]
---

# List grants with filters

`POST /api/v1/iga/grants/list`

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**

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

## Query parameters

- `search_key` string
- `sort_order` 'CREATED_AT_ASC' | 'CREATED_AT_DESC' | 'UPDATED_AT_ASC' | 'UPDATED_AT_DESC' | 'NAME_ASC' | 'NAME_DESC' | 'PUBLISHED_DESC' | 'UNPUBLISHED_DESC' | 'EXPIRES_AT_ASC' | 'EXPIRES_AT_DESC' | 'GRANTED_AT_ASC' | 'GRANTED_AT_DESC'
- `policy_id` string
- `app_id` integer
- `page` integer
- `per_page` integer
- `next_page_token` string
- `ids` string

## Headers

- `X-Api-Key` string, required
- `X-Workspace-Id` string

## Request body

- ApiV1IgaGrantsListPostRequestBodyContentApplicationJsonSchemaItems[]
  - `attribute` string
  - `operator` 'EQUALS' | 'NOT_EQUALS' | 'CONTAINS' | 'NOT_CONTAINS' | 'IN' | 'NOT_IN' | 'GREATER_THAN' | 'LESS_THAN' | 'GREATER_THAN_EQUALS' | 'LESS_THAN_EQUALS' | 'IS_BETWEEN' | 'IS_NULL' | 'IS_NOT_NULL' | 'STARTS_WITH' | 'ENDS_WITH' | 'TEXT_CONTAINS' | 'TEXT_DOES_NOT_CONTAINS' | 'IS_ANY_OF' | 'IS_NOT_ANY_OF' | 'IS_EXACTLY' | 'IS_ON_OR_BEFORE' | 'IS_ON_OR_AFTER' | 'IS_WITHIN'
  - `values` ApiV1IgaGrantsListPostRequestBodyContentApplicationJsonSchemaItemsValuesItems[]
    - `value` ApiV1IgaGrantsListPostRequestBodyContentApplicationJsonSchemaItemsValuesItemsValue
    - `nested_filter` unknown

## Response `200`

Successful response

- AccessManagementPostapiV1IgaGrantsListResponse200 — Empty response body

## Changes

- **2026-08-22** `6223f7496274` — 1 breaking
  - for the `query` request parameter `search_key`, the minLength was increased from `0` to `1`
- **2026-08-12** `2ab1cf36239b` — 1 info
  - api operation id `postapi-v-1-iga-grants-list` removed and replaced with `postapi_v1_iga_grants_list`

[Change history](https://skmtc.dev/atomicwork/apis/atomicwork-public-api/changes/api/v1/iga/grants/list/post.md)

---

[API](https://skmtc.dev/atomicwork/apis/atomicwork-public-api.md) · [All operations](https://skmtc.dev/atomicwork/apis/atomicwork-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/atomicwork/atomicwork-public-api/revisions/6223f7496274/schema)