> ## Documentation Index > Fetch the complete documentation index at: https://docs.seam.co/llms.txt > Use this file to discover all available pages before exploring further. # List Access Grants > Gets an Access Grant. ## OpenAPI ````yaml /openapi.json post /access_grants/list openapi: 3.0.0 info: title: Seam Connect version: 1.0.0 servers: - url: https://connect.getseam.com security: [] tags: - description: access_codes name: /access_codes - description: acs name: /acs - description: action_attempts name: /action_attempts - description: client_sessions name: /client_sessions - description: connected_accounts name: /connected_accounts - description: connect_webviews name: /connect_webviews - description: devices name: /devices - description: events name: /events - description: health name: /health - description: locks name: /locks - description: networks name: /networks - description: noise_sensors name: /noise_sensors - description: phones name: /phones - description: thermostats name: /thermostats - description: user_identities name: /user_identities - description: webhooks name: /webhooks - description: workspaces name: /workspaces paths: /access_grants/list: post: tags: [] summary: List Access Grants description: Gets an Access Grant. operationId: accessGrantsListPost requestBody: content: application/json: schema: properties: access_code_id: description: >- ID of the access code by which you want to filter the list of Access Grants. format: uuid type: string access_grant_ids: description: IDs of the access grants to retrieve. items: format: uuid type: string type: array access_grant_key: description: >- Filter Access Grants by access_grant_key. Use null to filter for Access Grants without an access_grant_key. nullable: true type: string acs_entrance_id: description: >- ID of the entrance by which you want to filter the list of Access Grants. format: uuid type: string acs_system_id: description: >- ID of the access system by which you want to filter the list of Access Grants. format: uuid type: string customer_key: description: Customer key for which you want to list access grants. type: string device_id: description: >- ID of the device by which you want to filter the list of Access Grants. format: uuid type: string limit: default: 500 description: Numerical limit on the number of access grants to return. format: float type: number location_id: deprecated: true format: uuid type: string x-deprecated: Use `space_id`. page_cursor: description: >- Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`. nullable: true type: string reservation_key: description: Filter Access Grants by reservation_key. type: string space_id: description: >- ID of the space by which you want to filter the list of Access Grants. format: uuid type: string user_identity_id: description: >- ID of user identity by which you want to filter the list of Access Grants. format: uuid type: string type: object responses: '200': content: application/json: schema: properties: access_grants: items: $ref: '#/components/schemas/access_grant' type: array ok: type: boolean pagination: $ref: '#/components/schemas/pagination' required: - access_grants - pagination - ok type: object description: OK '400': description: Bad Request '401': description: Unauthorized security: - pat_with_workspace: [] - console_session_with_workspace: [] - api_key: [] - client_session_with_customer: [] x-codeSamples: - lang: javascript label: Seam SDK source: |- await seam.accessGrants.list({ user_identity_id: "f7620fcf-d92f-471e-b97e-3806daeebd40", acs_system_id: "9f169742-048a-4105-84e3-bd1e0f9dc790", acs_entrance_id: "2673b363-4748-4a64-8075-f669c862ec74", space_id: "1d20c47d-3cc0-41ca-9917-bc798d071543", }); /* [ { "access_grant": { "access_grant_id": "704eadf0-a0a2-4715-b0e1-2f002dc1b6e0", "access_method_ids": [ "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" ], "created_at": "2025-06-16T16:54:17.946606Z", "display_name": "My Access Grant", "ends_at": "2025-06-18T16:54:17.946606Z", "instant_key_url": "https://ik.seam.co/ABCXYZ", "requested_access_methods": [ { "display_name": "PIN Code Credential", "mode": "code", "created_at": "2025-06-16T16:54:17.946606Z", "created_access_method_ids": [ "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" ] }, { "display_name": "Card Credential", "mode": "card", "created_at": "2025-06-16T16:54:19.946606Z", "created_access_method_ids": [ "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" ] }, { "display_name": "Mobile Key Credential", "mode": "mobile_key", "created_at": "2025-06-16T16:54:21.946606Z", "created_access_method_ids": [ "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" ] } ], "space_ids": [ "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a" ], "starts_at": "2025-06-16T16:54:17.946606Z", "user_identity_id": "f7620fcf-d92f-471e-b97e-3806daeebd40", "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7" } } ] */ - lang: bash label: cURL source: >- curl --include --request POST "https://connect.getseam.com/access_grants/list" \ --header "Authorization: Bearer $SEAM_API_KEY" \ --json @- < [ { "access_grant" => { access_grant_id: "704eadf0-a0a2-4715-b0e1-2f002dc1b6e0", access_method_ids: %w[ a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d 5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f ], created_at: "2025-06-16T16:54:17.946606Z", display_name: "My Access Grant", ends_at: "2025-06-18T16:54:17.946606Z", instant_key_url: "https://ik.seam.co/ABCXYZ", requested_access_methods: [ { display_name: "PIN Code Credential", mode: "code", created_at: "2025-06-16T16:54:17.946606Z", created_access_method_ids: ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"], }, { display_name: "Card Credential", mode: "card", created_at: "2025-06-16T16:54:19.946606Z", created_access_method_ids: ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], }, { display_name: "Mobile Key Credential", mode: "mobile_key", created_at: "2025-06-16T16:54:21.946606Z", created_access_method_ids: ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], }, ], space_ids: %w[1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d 7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a], starts_at: "2025-06-16T16:54:17.946606Z", user_identity_id: "f7620fcf-d92f-471e-b97e-3806daeebd40", workspace_id: "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7", }, }, ] - lang: php label: Seam SDK source: |- $seam->access_grants->list( user_identity_id: "f7620fcf-d92f-471e-b97e-3806daeebd40", acs_system_id: "9f169742-048a-4105-84e3-bd1e0f9dc790", acs_entrance_id: "2673b363-4748-4a64-8075-f669c862ec74", space_id: "1d20c47d-3cc0-41ca-9917-bc798d071543", ); // [ [ "access_grant" => [ "access_grant_id" => "704eadf0-a0a2-4715-b0e1-2f002dc1b6e0", "access_method_ids" => [ "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", ], "created_at" => "2025-06-16T16:54:17.946606Z", "display_name" => "My Access Grant", "ends_at" => "2025-06-18T16:54:17.946606Z", "instant_key_url" => "https://ik.seam.co/ABCXYZ", "requested_access_methods" => [ [ "display_name" => "PIN Code Credential", "mode" => "code", "created_at" => "2025-06-16T16:54:17.946606Z", "created_access_method_ids" => [ "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", ], ], [ "display_name" => "Card Credential", "mode" => "card", "created_at" => "2025-06-16T16:54:19.946606Z", "created_access_method_ids" => [ "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", ], ], [ "display_name" => "Mobile Key Credential", "mode" => "mobile_key", "created_at" => "2025-06-16T16:54:21.946606Z", "created_access_method_ids" => [ "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", ], ], ], "space_ids" => [ "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a", ], "starts_at" => "2025-06-16T16:54:17.946606Z", "user_identity_id" => "f7620fcf-d92f-471e-b97e-3806daeebd40", "workspace_id" => "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7", ], ], ]; - lang: bash label: Seam CLI source: >- seam access-grants list --user_identity_id "f7620fcf-d92f-471e-b97e-3806daeebd40" --acs_system_id "9f169742-048a-4105-84e3-bd1e0f9dc790" --acs_entrance_id "2673b363-4748-4a64-8075-f669c862ec74" --space_id "1d20c47d-3cc0-41ca-9917-bc798d071543" # [ # { # "access_grant": { # "access_grant_id": "704eadf0-a0a2-4715-b0e1-2f002dc1b6e0", # "access_method_ids": [ # "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", # "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", # "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" # ], # "created_at": "2025-06-16T16:54:17.946606Z", # "display_name": "My Access Grant", # "ends_at": "2025-06-18T16:54:17.946606Z", # "instant_key_url": "https://ik.seam.co/ABCXYZ", # "requested_access_methods": [ # { # "display_name": "PIN Code Credential", # "mode": "code", # "created_at": "2025-06-16T16:54:17.946606Z", # "created_access_method_ids": [ # "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" # ] # }, # { # "display_name": "Card Credential", # "mode": "card", # "created_at": "2025-06-16T16:54:19.946606Z", # "created_access_method_ids": [ # "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" # ] # }, # { # "display_name": "Mobile Key Credential", # "mode": "mobile_key", # "created_at": "2025-06-16T16:54:21.946606Z", # "created_access_method_ids": [ # "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" # ] # } # ], # "space_ids": [ # "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", # "7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a" # ], # "starts_at": "2025-06-16T16:54:17.946606Z", # "user_identity_id": "f7620fcf-d92f-471e-b97e-3806daeebd40", # "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7" # } # } # ] components: schemas: access_grant: description: >- Represents an Access Grant. Access Grants enable you to grant a user identity access to spaces, entrances, and devices through one or more access methods, such as mobile keys, plastic cards, and PIN codes. You can create an Access Grant for an existing user identity, or you can create a new user identity *while* creating the new Access Grant. properties: access_grant_id: description: ID of the Access Grant. format: uuid type: string access_grant_key: description: Unique key for the access grant within the workspace. type: string access_method_ids: description: IDs of the access methods created for the Access Grant. items: format: uuid type: string type: array client_session_token: description: >- Client Session Token. Only returned if the Access Grant has a mobile_key access method. type: string created_at: description: Date and time at which the Access Grant was created. format: date-time type: string customization_profile_id: description: ID of the customization profile associated with the Access Grant. format: uuid type: string display_name: description: Display name of the Access Grant. type: string ends_at: description: Date and time at which the Access Grant ends. format: date-time nullable: true type: string errors: description: >- Errors associated with the [access grant](https://docs.seam.co/use-cases/granting-access). items: discriminator: propertyName: error_code oneOf: - properties: created_at: description: Date and time at which Seam created the error. format: date-time type: string error_code: description: >- Unique identifier of the type of error. Enables quick recognition and categorization of the issue. enum: - cannot_create_requested_access_methods type: string message: description: >- Detailed description of the error. Provides insights into the issue and potentially how to rectify it. type: string missing_device_ids: description: >- 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. items: format: uuid type: string type: array required: - created_at - message - error_code type: object type: array instant_key_url: description: >- Instant Key URL. Only returned if the Access Grant has a single mobile_key access_method. format: uri type: string location_ids: deprecated: true items: format: uuid type: string type: array x-deprecated: Use `space_ids`. name: description: >- Name of the Access Grant. If not provided, the display name will be computed. nullable: true type: string pending_mutations: description: >- List of pending mutations for the access grant. This shows updates that are in progress. items: discriminator: propertyName: mutation_code oneOf: - description: >- Seam is in the process of updating the devices/spaces associated with this access grant. properties: created_at: description: Date and time at which the mutation was created. format: date-time type: string from: description: Previous location configuration. properties: device_ids: description: Previous device IDs where access codes existed. items: format: uuid type: string type: array required: - device_ids type: object message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is in the process of updating the spaces (devices) associated with this access grant. enum: - updating_spaces type: string to: description: New location configuration. properties: common_code_key: description: >- Common code key to ensure PIN code reuse across devices. nullable: true type: string device_ids: description: New device IDs where access codes should be created. items: format: uuid type: string type: array required: - device_ids type: object required: - created_at - message - mutation_code - from - to type: object - description: >- Seam is in the process of updating the access times for this access grant. properties: access_method_ids: description: IDs of the access methods being updated. items: format: uuid type: string type: array created_at: description: Date and time at which the mutation was created. format: date-time type: string from: description: Previous access time configuration. properties: ends_at: description: Previous end time for access. format: date-time nullable: true type: string starts_at: description: Previous start time for access. format: date-time nullable: true type: string required: - starts_at - ends_at type: object message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is in the process of updating the access times for this access grant. enum: - updating_access_times type: string to: description: New access time configuration. properties: ends_at: description: New end time for access. format: date-time nullable: true type: string starts_at: description: New start time for access. format: date-time nullable: true type: string required: - starts_at - ends_at type: object required: - created_at - message - mutation_code - access_method_ids - from - to type: object type: array requested_access_methods: description: Access methods that the user requested for the Access Grant. items: properties: code: description: >- Specific PIN code to use for this access method. Only applicable when mode is 'code'. maxLength: 9 minLength: 4 pattern: ^\d+$ type: string created_access_method_ids: description: >- IDs of the access methods created for the requested access method. items: format: uuid type: string type: array created_at: description: >- Date and time at which the requested access method was added to the Access Grant. format: date-time type: string display_name: description: Display name of the access method. type: string instant_key_max_use_count: description: >- Maximum number of times the instant key can be used. Only applicable when mode is 'mobile_key'. Defaults to 1 if not specified. minimum: 1 type: integer mode: description: >- Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`. enum: - code - card - mobile_key - cloud_key type: string required: - display_name - mode - created_at - created_access_method_ids type: object type: array reservation_key: description: Reservation key for the access grant. type: string space_ids: description: IDs of the spaces to which the Access Grant gives access. items: format: uuid type: string type: array starts_at: description: Date and time at which the Access Grant starts. format: date-time type: string user_identity_id: description: ID of user identity to which the Access Grant gives access. format: uuid type: string warnings: type: array description: >- Warnings associated with the [access grant](https://docs.seam.co/use-cases/granting-access). items: type: object properties: error_code: type: string description: Error or warning code. message: type: string description: Human-readable description. created_at: type: string format: date-time description: When this error or warning was generated. workspace_id: description: ID of the Seam workspace associated with the Access Grant. format: uuid type: string required: - workspace_id - access_grant_id - user_identity_id - location_ids - space_ids - requested_access_methods - access_method_ids - name - display_name - created_at - starts_at - ends_at - warnings - errors - pending_mutations type: object x-draft: Early access. x-route-path: /access_grants pagination: description: Information about the current page of results. properties: has_next_page: description: Indicates whether there is another page of results after this one. type: boolean next_page_cursor: description: >- Opaque value that can be used to select the next page of results via the `page_cursor` parameter. nullable: true type: string next_page_url: description: URL to get the next page of results. format: uri nullable: true type: string required: - next_page_cursor - has_next_page - next_page_url type: object securitySchemes: pat_with_workspace: bearerFormat: API Token scheme: bearer type: http console_session_with_workspace: bearerFormat: Console Session Token scheme: bearer type: http api_key: bearerFormat: API Key scheme: bearer type: http client_session_with_customer: bearerFormat: Customer Client Session Token scheme: bearer type: http ````