---
title: "List Access Grants"
method: POST
path: "/access_grants/list"
---

# List Access Grants

`POST /access_grants/list`

Gets an Access Grant.

## Request body

- object
  - `access_code_id` string, uuid — ID of the access code by which you want to filter the list of Access Grants.
  - `access_grant_ids` string[] — IDs of the access grants to retrieve.
  - `access_grant_key` string, nullable — Filter Access Grants by access_grant_key. Use null to filter for Access Grants without an access_grant_key.
  - `acs_entrance_id` string, uuid — ID of the entrance by which you want to filter the list of Access Grants.
  - `acs_system_id` string, uuid — ID of the access system by which you want to filter the list of Access Grants.
  - `customer_key` string — Customer key for which you want to list access grants.
  - `device_id` string, uuid — ID of the device by which you want to filter the list of Access Grants.
  - `limit` number, float — Numerical limit on the number of access grants to return.
  - `location_id` string, uuid — Deprecated. Use `space_id`.
  - `page_cursor` string, nullable — Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
  - `reservation_key` string — Filter Access Grants by reservation_key.
  - `space_id` string, uuid — ID of the space by which you want to filter the list of Access Grants.
  - `user_identity_id` string, uuid — ID of user identity by which you want to filter the list of Access Grants.

## Response `200`

OK

- object
  - `access_grants` AccessGrant[], required
    - `access_grant_id` string, uuid, required — ID of the Access Grant.
    - `access_grant_key` string — Unique key for the access grant within the workspace.
    - `access_method_ids` string[], required — IDs of the access methods created for the Access Grant.
    - `client_session_token` string — Client Session Token. Only returned if the Access Grant has a mobile_key access method.
    - `created_at` string, date-time, required — Date and time at which the Access Grant was created.
    - `customization_profile_id` string, uuid — ID of the customization profile associated with the Access Grant.
    - `display_name` string, required — Display name of the Access Grant.
    - `ends_at` string, date-time, nullable, required — Date and time at which the Access Grant ends.
    - `errors` object[], required — Errors associated with the [access grant](/use-cases/granting-access).
      - `created_at` string, date-time, required — Date and time at which Seam created the error.
      - `error_code` 'cannot_create_requested_access_methods', required — Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
      - `message` string, required — Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
      - `missing_device_ids` string[] — IDs of the devices that did not receive an access code at grant creation. Use these to identify which specific devices failed when the message reports a partial failure.
    - `instant_key_url` string, uri — Instant Key URL. Only returned if the Access Grant has a single mobile_key access_method.
    - `location_ids` string[], required — Deprecated. Use `space_ids`.
    - `name` string, nullable, required — Name of the Access Grant. If not provided, the display name will be computed.
    - `pending_mutations` union[], required — List of pending mutations for the access grant. This shows updates that are in progress.
      - union
        - object — Seam is in the process of updating the devices/spaces associated with this access grant.
          - `created_at` string, date-time, required — Date and time at which the mutation was created.
          - `from` object, required — Previous location configuration.
            - `device_ids` string[], required — Previous device IDs where access codes existed.
          - `message` string, required — Detailed description of the mutation.
          - `mutation_code` 'updating_spaces', required — Mutation code to indicate that Seam is in the process of updating the spaces (devices) associated with this access grant.
          - `to` object, required — New location configuration.
            - `common_code_key` string, nullable — Common code key to ensure PIN code reuse across devices.
            - `device_ids` string[], required — New device IDs where access codes should be created.
        - object — Seam is in the process of updating the access times for this access grant.
          - `access_method_ids` string[], required — IDs of the access methods being updated.
          - `created_at` string, date-time, required — Date and time at which the mutation was created.
          - `from` object, required — Previous access time configuration.
            - `ends_at` string, date-time, nullable, required — Previous end time for access.
            - `starts_at` string, date-time, nullable, required — Previous start time for access.
          - `message` string, required — Detailed description of the mutation.
          - `mutation_code` 'updating_access_times', required — Mutation code to indicate that Seam is in the process of updating the access times for this access grant.
          - `to` object, required — New access time configuration.
            - `ends_at` string, date-time, nullable, required — New end time for access.
            - `starts_at` string, date-time, nullable, required — New start time for access.
    - `requested_access_methods` object[], required — Access methods that the user requested for the Access Grant.
      - `code` string — Specific PIN code to use for this access method. Only applicable when mode is 'code'.
      - `created_access_method_ids` string[], required — IDs of the access methods created for the requested access method.
      - `created_at` string, date-time, required — Date and time at which the requested access method was added to the Access Grant.
      - `display_name` string, required — Display name of the access method.
      - `instant_key_max_use_count` integer — Maximum number of times the instant key can be used. Only applicable when mode is 'mobile_key'. Defaults to 1 if not specified.
      - `mode` 'code' | 'card' | 'mobile_key' | 'cloud_key', required — Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`.
    - `reservation_key` string — Reservation key for the access grant.
    - `space_ids` string[], required — IDs of the spaces to which the Access Grant gives access.
    - `starts_at` string, date-time, required — Date and time at which the Access Grant starts.
    - `user_identity_id` string, uuid, required — ID of user identity to which the Access Grant gives access.
    - `warnings` object[], required — Warnings associated with the [access grant](/use-cases/granting-access).
      - `error_code` string — Error or warning code.
      - `message` string — Human-readable description.
      - `created_at` string, date-time — When this error or warning was generated.
    - `workspace_id` string, uuid, required — ID of the Seam workspace associated with the Access Grant.
  - `pagination` Pagination, required — Information about the current page of results.
    - `has_next_page` boolean, required — Indicates whether there is another page of results after this one.
    - `next_page_cursor` string, nullable, required — Opaque value that can be used to select the next page of results via the `page_cursor` parameter.
    - `next_page_url` string, uri, nullable, required — URL to get the next page of results.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

---

[API](https://skmtc.net/seam/apis/seam-connect.md) · [All operations](https://skmtc.net/seam/apis/seam-connect/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/seam/seam-connect/versions/00c35395ce12/schema)