From 8e72213b281069acd7ca12b7a190901d99e48038 Mon Sep 17 00:00:00 2001 From: dawnho Date: Tue, 9 Jun 2026 23:34:48 -0700 Subject: [PATCH 01/36] =?UTF-8?q?feat:=20restructure=20Granting=20Access?= =?UTF-8?q?=20section=20into=20create=20=E2=86=92=20deliver=20=E2=86=92=20?= =?UTF-8?q?manage=20lifecycle?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorganize the Mintlify Granting Access docs from a flat list of endpoint-reference pages into a guided lifecycle: Create: - Rewrite "Creating an Access Grant" as a concise 2-step tutorial (create → deliver) with one multi-language example - Add reservation callout for override-based ACS systems Deliver: - Add dedicated delivery pages: PIN codes, mobile keys, instant keys, key cards, cloud keys Manage: - Add "Managing Access Grants" (update schedule/resources, delete) with accurate event documentation per update type - Add "Managing Access Methods" (add/revoke individual credentials) with revoke-and-replace pattern Consolidate: - Remove 7 redundant pages (quick start, retrieving, delivering overview, updating, revoking, deleting) - Add redirects for all removed pages - Convert Tabs/Tab to CodeGroup across all Mintlify guide sections Co-Authored-By: Claude Opus 4.6 --- .gitbook.yaml | 7 +- docs/guides/SUMMARY.md | 8 +- ...eating-and-encoding-card-access-methods.md | 2 +- docs/guides/quickstart.md | 2 +- .../use-cases/granting-access/README.md | 12 +- .../access-grant-quick-start.md | 5 +- .../creating-an-access-grant-using-devices.md | 767 --------- ...reating-an-access-grant-using-entrances.md | 913 ----------- .../creating-an-access-grant-using-spaces.md | 936 ----------- .../creating-an-access-grant.md | 1435 +++++++++++++++++ .../granting-access/using-cloud-keys.md | 2 +- .../granting-access/using-instant-keys.md | 209 +++ .../granting-access/using-key-cards.md | 470 ++++++ .../granting-access/using-mobile-keys.md | 382 +++++ .../granting-access/using-pin-codes.md | 460 ++++++ mintlify-docs/SUMMARY.mdx | 9 +- mintlify-docs/docs.json | 20 +- ...ating-and-encoding-card-access-methods.mdx | 2 +- mintlify-docs/quickstart.mdx | 2 +- .../access-grant-quick-start.mdx | 5 +- ...creating-an-access-grant-using-devices.mdx | 633 -------- ...eating-an-access-grant-using-entrances.mdx | 783 --------- .../creating-an-access-grant-using-spaces.mdx | 806 --------- .../creating-an-access-grant.mdx | 1435 +++++++++++++++++ .../use-cases/granting-access/index.mdx | 22 +- .../granting-access/using-instant-keys.mdx | 185 +++ .../granting-access/using-key-cards.mdx | 365 +++++ .../granting-access/using-mobile-keys.mdx | 308 ++++ .../granting-access/using-pin-codes.mdx | 357 ++++ 29 files changed, 5659 insertions(+), 4883 deletions(-) delete mode 100644 docs/guides/use-cases/granting-access/creating-an-access-grant-using-devices.md delete mode 100644 docs/guides/use-cases/granting-access/creating-an-access-grant-using-entrances.md delete mode 100644 docs/guides/use-cases/granting-access/creating-an-access-grant-using-spaces.md create mode 100644 docs/guides/use-cases/granting-access/creating-an-access-grant.md create mode 100644 docs/guides/use-cases/granting-access/using-instant-keys.md create mode 100644 docs/guides/use-cases/granting-access/using-key-cards.md create mode 100644 docs/guides/use-cases/granting-access/using-mobile-keys.md create mode 100644 docs/guides/use-cases/granting-access/using-pin-codes.md delete mode 100644 mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-devices.mdx delete mode 100644 mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-entrances.mdx delete mode 100644 mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-spaces.mdx create mode 100644 mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx create mode 100644 mintlify-docs/use-cases/granting-access/using-instant-keys.mdx create mode 100644 mintlify-docs/use-cases/granting-access/using-key-cards.mdx create mode 100644 mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx create mode 100644 mintlify-docs/use-cases/granting-access/using-pin-codes.mdx diff --git a/.gitbook.yaml b/.gitbook.yaml index bb184ee18..2a543ae9b 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -25,8 +25,11 @@ redirects: capability-guides/thermostats/creating-and-managing-climate-schedules: capability-guides/thermostats/creating-and-managing-thermostat-schedules.md capability-guides/access-grants: use-cases/granting-access/README.md capability-guides/access-grants/access-grant-quick-start: use-cases/granting-access/access-grant-quick-start.md - capability-guides/access-grants/creating-an-access-grant-using-entrances: use-cases/granting-access/creating-an-access-grant-using-entrances.md - capability-guides/access-grants/creating-an-access-grant-using-spaces: use-cases/granting-access/creating-an-access-grant-using-spaces.md + capability-guides/access-grants/creating-an-access-grant-using-entrances: use-cases/granting-access/creating-an-access-grant.md + capability-guides/access-grants/creating-an-access-grant-using-spaces: use-cases/granting-access/creating-an-access-grant.md + use-cases/granting-access/creating-an-access-grant-using-devices: use-cases/granting-access/creating-an-access-grant.md + use-cases/granting-access/creating-an-access-grant-using-spaces: use-cases/granting-access/creating-an-access-grant.md + use-cases/granting-access/creating-an-access-grant-using-entrances: use-cases/granting-access/creating-an-access-grant.md capability-guides/access-grants/delivering-access-methods: use-cases/granting-access/delivering-access-methods.md capability-guides/access-grants/reservation-access-grants: use-cases/granting-access/reservation-access-grants.md capability-guides/access-grants/retrieving-access-grants-and-access-methods: use-cases/granting-access/retrieving-access-grants-and-access-methods.md diff --git a/docs/guides/SUMMARY.md b/docs/guides/SUMMARY.md index 5d0105c57..a45db6714 100644 --- a/docs/guides/SUMMARY.md +++ b/docs/guides/SUMMARY.md @@ -8,10 +8,12 @@ * [Granting Access](use-cases/granting-access/README.md) * [Access Grant Quick Start](use-cases/granting-access/access-grant-quick-start.md) - * [Creating an Access Grant Using Devices](use-cases/granting-access/creating-an-access-grant-using-devices.md) - * [Creating an Access Grant Using Spaces](use-cases/granting-access/creating-an-access-grant-using-spaces.md) - * [Creating an Access Grant Using Entrances](use-cases/granting-access/creating-an-access-grant-using-entrances.md) + * [Creating an Access Grant](use-cases/granting-access/creating-an-access-grant.md) * [Delivering Access Methods](use-cases/granting-access/delivering-access-methods.md) + * [Using PIN Codes](use-cases/granting-access/using-pin-codes.md) + * [Using Mobile Keys](use-cases/granting-access/using-mobile-keys.md) + * [Using Instant Keys](use-cases/granting-access/using-instant-keys.md) + * [Using Key Cards](use-cases/granting-access/using-key-cards.md) * [Using Cloud Keys](use-cases/granting-access/using-cloud-keys.md) * [Reservation Access Grants](use-cases/granting-access/reservation-access-grants.md) * [Retrieving Access Grants and Access Methods](use-cases/granting-access/retrieving-access-grants-and-access-methods.md) diff --git a/docs/guides/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods.md b/docs/guides/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods.md index a5b933bc3..d3f38cc42 100644 --- a/docs/guides/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods.md +++ b/docs/guides/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods.md @@ -30,7 +30,7 @@ Once you have written an access method to a card, you cannot reuse the access me This example shows how to create a card access method as part of an Access Grant. Note that the `is_encoding_required` property of the resulting access method is `true`, which means that the access method must be encoded onto a card. Further, once you've encoded the access method on to the card, the `is_issued` property changes to `true`, and the `issued_at` property indicates the date and time at which the encoding occurred. -For more details about creating Access Grants, see [Creating an Access Grant Using Entrances](../../../use-cases/granting-access/creating-an-access-grant-using-entrances.md) and [Creating an Access Grant Using Spaces](../../../use-cases/granting-access/creating-an-access-grant-using-spaces.md). +For more details about creating Access Grants, see [Creating an Access Grant](../../../use-cases/granting-access/creating-an-access-grant.md). {% tabs %} {% tab title="JavaScript" %} diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.md index 6fce2825b..e93e08675 100644 --- a/docs/guides/quickstart.md +++ b/docs/guides/quickstart.md @@ -383,7 +383,7 @@ Here are some ideas of what you can do next... ### Go Deeper on Granting Access -You just created your first Access Grant. The same API issues mobile keys, [Instant Keys](capability-guides/instant-keys/README.md), and plastic cards, grants access to multiple devices and [access system entrances](use-cases/granting-access/creating-an-access-grant-using-entrances.md) in one call, and manages the full credential lifecycle. See the [Granting Access guide](use-cases/granting-access/README.md). +You just created your first Access Grant. The same API issues mobile keys, [Instant Keys](capability-guides/instant-keys/README.md), and plastic cards, grants access to multiple devices and [access system entrances](use-cases/granting-access/creating-an-access-grant.md) in one call, and manages the full credential lifecycle. See the [Granting Access guide](use-cases/granting-access/README.md). You can also control devices directly—for example, [lock and unlock doors](low-level-apis/smart-locks/lock-and-unlock.md) remotely. diff --git a/docs/guides/use-cases/granting-access/README.md b/docs/guides/use-cases/granting-access/README.md index 3569bd283..a20942450 100644 --- a/docs/guides/use-cases/granting-access/README.md +++ b/docs/guides/use-cases/granting-access/README.md @@ -135,9 +135,9 @@ Access Grants work across the entire Seam provider lineup: We recommend learning Access Grants in three steps, from the simplest setup to the most advanced: -1. **One device.** Connect a smart lock and create an Access Grant with a single `device_id` and a `code` access method. See [Creating an Access Grant Using Devices](creating-an-access-grant-using-devices.md). -2. **Multiple devices and spaces.** Pass several `device_ids` in one call to grant access to a set of locks at once. To manage groups of access points by name—for example, everything a guest in Unit 101 needs—organize them into [spaces](creating-an-access-grant-using-spaces.md) and grant access by `space_id`. -3. **Access control systems.** Connect an ACS, such as Salto, Visionline, or Brivo, and grant access to entrances with `acs_entrance_ids`. This path can involve additional setup, such as licenses, on-premises connections through Seam Bridge, mobile key configuration, and [reservations](reservation-access-grants.md) for offline-override systems. See [Creating an Access Grant Using Entrances](creating-an-access-grant-using-entrances.md). +1. **One device.** Connect a smart lock and create an Access Grant with a single `device_id` and a `code` access method. See [Creating an Access Grant](creating-an-access-grant.md#using-device-ids). +2. **Multiple devices and spaces.** Pass several `device_ids` in one call to grant access to a set of locks at once. To manage groups of access points by name—for example, everything a guest in Unit 101 needs—organize them into [spaces](creating-an-access-grant.md#using-space-ids) and grant access by `space_id`. +3. **Access control systems.** Connect an ACS, such as Salto, Visionline, or Brivo, and grant access to entrances with `acs_entrance_ids`. This path can involve additional setup, such as licenses, on-premises connections through Seam Bridge, mobile key configuration, and [reservations](reservation-access-grants.md) for offline-override systems. See [Creating an Access Grant](creating-an-access-grant.md#using-entrance-ids). *** @@ -153,7 +153,7 @@ An Access Grant includes the following characteristics: The Access Grant process consists of the following steps: -
StepDescription
  1. Connect your devices or access system to Seam.
To connect your devices or access system to Seam, we recommend embedding a Connect Webview in your application. The Connect Webview flow guides the property manager through each step of the connection process.
For standalone smart locks, this is all the setup you need.
For on-premises access systems, use Seam Bridge to connect the access system securely to Seam. For details, see Connect an Access System to Seam.
  1. (Access systems only) Set up your site.
If you are granting access to access system entrances, confirm hardware capabilities and make sure that you have the required licenses. For example, if you plan to use mobile keys or Instant Keys, your lock hardware must support Bluetooth Low Energy (BLE) keys. Also, to use mobile keys with your access system, you may need to purchase licenses or subscriptions to activate certain software features. These requirements vary by access system. For details, see Setting Up Your Site for Instant Keys and the system integration guide for your access system.
  1. (Optional) Set up spaces to organize access points into logical groups.
You can use spaces to create groups of devices and entrances for efficiency. For example, a user staying in Room 101 may need access to the Room 101 door, the main entrance door, and the nearest elevator. You could create a space that includes these access points and then use this space when creating an Access Grant.
For details, see spaces.
  1. Create a user identity.
User identities represent your users—the people to whom you want to grant access. You can create a user identity before creating an Access Grant, or you can create a user identity as part of creating the Access Grant.
See Managing Mobile App User Accounts with User Identities.
  1. Create an Access Grant.
When you create an Access Grant, you specify the user identity to whom you want to grant access, the access schedule, the set of devices, entrances, or spaces, and one or more access methods that you want to request.
See Creating an Access Grant Using Devices, Creating an Access Grant Using Spaces, and Creating an Access Grant Using Entrances.
You can poll for access method status changes or watch for Access Grant and access method lifecycle events that alert you to next steps, such as how and when to deliver each created access method to your user.
  1. Deliver the access method to the user.

Once Seam alerts you that your access methods are ready, deliver them to your user. Delivery steps depend on the mode of access, such as PIN code, plastic key card, or mobile key.

  • If you have created an Access Grant that includes a code access method, retrieve the access method to get the PIN code and share it with your user.
  • If you have created an Access Grant that includes a card access method, you may need to encode the card using the Seam encoders API.
  • If you have created an Access Grant that includes a mobile key, you can use the Seam mobile SDKs to develop your mobile app that delivers these mobile keys to your users.
  • Each mobile key also includes an Instant Key URL. To share this Instant Key with your user, send it through text or email or embed it in your own app.

See Delivering Access Methods.

+
StepDescription
  1. Connect your devices or access system to Seam.
To connect your devices or access system to Seam, we recommend embedding a Connect Webview in your application. The Connect Webview flow guides the property manager through each step of the connection process.
For standalone smart locks, this is all the setup you need.
For on-premises access systems, use Seam Bridge to connect the access system securely to Seam. For details, see Connect an Access System to Seam.
  1. (Access systems only) Set up your site.
If you are granting access to access system entrances, confirm hardware capabilities and make sure that you have the required licenses. For example, if you plan to use mobile keys or Instant Keys, your lock hardware must support Bluetooth Low Energy (BLE) keys. Also, to use mobile keys with your access system, you may need to purchase licenses or subscriptions to activate certain software features. These requirements vary by access system. For details, see Setting Up Your Site for Instant Keys and the system integration guide for your access system.
  1. (Optional) Set up spaces to organize access points into logical groups.
You can use spaces to create groups of devices and entrances for efficiency. For example, a user staying in Room 101 may need access to the Room 101 door, the main entrance door, and the nearest elevator. You could create a space that includes these access points and then use this space when creating an Access Grant.
For details, see spaces.
  1. Create a user identity.
User identities represent your users—the people to whom you want to grant access. You can create a user identity before creating an Access Grant, or you can create a user identity as part of creating the Access Grant.
See Managing Mobile App User Accounts with User Identities.
  1. Create an Access Grant.
When you create an Access Grant, you specify the user identity to whom you want to grant access, the access schedule, the set of devices, entrances, or spaces, and one or more access methods that you want to request.
See Creating an Access Grant.
You can poll for access method status changes or watch for Access Grant and access method lifecycle events that alert you to next steps, such as how and when to deliver each created access method to your user.
  1. Deliver the access method to the user.

Once Seam alerts you that your access methods are ready, deliver them to your user. Delivery steps depend on the mode of access, such as PIN code, plastic key card, or mobile key.

  • If you have created an Access Grant that includes a code access method, retrieve the access method to get the PIN code and share it with your user.
  • If you have created an Access Grant that includes a card access method, you may need to encode the card using the Seam encoders API.
  • If you have created an Access Grant that includes a mobile key, you can use the Seam mobile SDKs to develop your mobile app that delivers these mobile keys to your users.
  • Each mobile key also includes an Instant Key URL. To share this Instant Key with your user, send it through text or email or embed it in your own app.

See Delivering Access Methods.

*** @@ -192,9 +192,7 @@ When issuing Access Grants for these systems, you’ll need to use reservations To create your first Access Grant, see the [Access Grant Quick Start](access-grant-quick-start.md). Then, learn more in the following topics: -* [Creating an Access Grant Using Devices](creating-an-access-grant-using-devices.md) -* [Creating an Access Grant Using Spaces](creating-an-access-grant-using-spaces.md) -* [Creating an Access Grant Using Entrances](creating-an-access-grant-using-entrances.md) +* [Creating an Access Grant](creating-an-access-grant.md) * [Delivering Access Methods](delivering-access-methods.md) * [Access Grants API Reference](https://docs.seam.co/latest/api/access_grants/) * [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) diff --git a/docs/guides/use-cases/granting-access/access-grant-quick-start.md b/docs/guides/use-cases/granting-access/access-grant-quick-start.md index 1491d5491..d95e0d72a 100644 --- a/docs/guides/use-cases/granting-access/access-grant-quick-start.md +++ b/docs/guides/use-cases/granting-access/access-grant-quick-start.md @@ -9,7 +9,7 @@ description: >- In this quick start, create an Access Grant to give a user access to a set of access points. Access Grants are the default and recommended way to grant access to any physical space, irrespective of the locking hardware—standalone smart locks, access control systems, or a mix of both. With a single command you can define the "who, where, when, and how" for assigning a user access. {% hint style="success" %} -**Starting with a standalone smart lock?** The fastest first success is a single device and a PIN code: see the [Seam Quick Start](../../quickstart.md), which creates an Access Grant on a sandbox August lock, or [Creating an Access Grant Using Devices](creating-an-access-grant-using-devices.md). This quick start walks through the more advanced access system (ACS) path, including key cards, mobile keys, and Instant Keys. +**Starting with a standalone smart lock?** The fastest first success is a single device and a PIN code: see the [Seam Quick Start](../../quickstart.md), which creates an Access Grant on a sandbox August lock, or [Creating an Access Grant](creating-an-access-grant.md#using-device-ids). This quick start walks through the more advanced access system (ACS) path, including key cards, mobile keys, and Instant Keys. {% endhint %} In addition, this quick start shows you that, with Access Grants, it's easy to issue users access through multiple types of access methods, such as key cards, PIN codes, mobile keys, and Instant Keys. @@ -818,8 +818,7 @@ The way in which you deliver an access method depends on the mode of access. The Now that you've created your first Access Grant, learn more about Access Grants. -* [Creating an Access Grant Using Entrances](creating-an-access-grant-using-entrances.md) -* [Creating an Access Grant Using Spaces](creating-an-access-grant-using-spaces.md) +* [Creating an Access Grant](creating-an-access-grant.md) * [Delivering Access Methods](delivering-access-methods.md) * [Access Grants API Reference](https://docs.seam.co/latest/api/access_grants/) * [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) diff --git a/docs/guides/use-cases/granting-access/creating-an-access-grant-using-devices.md b/docs/guides/use-cases/granting-access/creating-an-access-grant-using-devices.md deleted file mode 100644 index 157aa1b53..000000000 --- a/docs/guides/use-cases/granting-access/creating-an-access-grant-using-devices.md +++ /dev/null @@ -1,767 +0,0 @@ ---- -description: >- - Learn how to create an Access Grant to give a user access to one or more - devices, such as standalone smart locks. ---- - -# Creating an Access Grant Using Devices - -Granting access to a device is the simplest form of an Access Grant. You specify the user, one or more device IDs, the access schedule, and the desired access methods, and Seam takes care of creating and managing the underlying credentials on each device. - -This path works for standalone smart locks—such as August, Yale, Schlage, igloohome, and TTLock devices—that are connected to Seam through a [Connect Webview](../../core-concepts/connect-webviews/). The devices do not need to be part of an access control system. - -An Access Grant defines the following characteristics: - -* User identity: The user to whom you want to grant access. -* Devices: The set of devices to which you want to grant the user access. -* Access schedule: The starting and ending times for access. -* Access methods: The modes of access, such as PIN codes and mobile keys. - -This topic describes how to create an Access Grant using device IDs. To learn how to organize devices and entrances into spaces and grant access to a whole space, see [Creating an Access Grant Using Spaces](creating-an-access-grant-using-spaces.md). To learn how to grant access to access system entrances, see [Creating an Access Grant Using Entrances](creating-an-access-grant-using-entrances.md). - -*** - -## Access Grant Creation Process - -To create an Access Grant: - -1. [Identify the devices](creating-an-access-grant-using-devices.md#identify-devices) to which you want to grant the user access. -2. [Create a user identity](creating-an-access-grant-using-devices.md#create-a-user-identity) for the user to whom you want to grant access. Alternately, you can create a new user identity as part of the Access Grant creation action. -3. [Create an Access Grant](creating-an-access-grant-using-devices.md#create-an-access-grant) for the user identity to define the devices to which the user should have access, the starting and ending times for this access, and the requested access methods, such as `code`. - - The action returns the created Access Grant. -4. [Retrieve the resulting access methods](creating-an-access-grant-using-devices.md#retrieve-the-access-methods) once they are issued. For a `code` access method, the returned access method includes the PIN code that you can deliver to your user. - -*** - -## Before You Begin - -To create an Access Grant for a device, first [connect](../../core-concepts/connect-webviews/) the device account to Seam. Then, confirm that the device supports access codes by checking its `can_program_online_access_codes` capability flag. - -{% hint style="info" %} -You can try this entire flow in a [sandbox workspace](../../core-concepts/workspaces/#sandbox-workspaces) using sandbox devices, such as the August sandbox locks. -{% endhint %} - -*** - -## Identify Devices - -List your devices and identify the ones to which you want to grant the user access. Check the `can_program_online_access_codes` capability flag for each device. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -const devices = await seam.devices.list(); - -const lock = devices.find( - (device) => device.can_program_online_access_codes -); -``` - -**Output:** - -```json -[ - { - "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name": "Front Door", - "can_program_online_access_codes": true, - ... - }, - ... -] -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/devices/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -**Output:** - -```json -{ - "devices": [ - { - "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name": "Front Door", - "can_program_online_access_codes": true, - ... - }, - ... - ] -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -devices = seam.devices.list() - -lock = next( - device for device in devices - if device.can_program_online_access_codes -) -``` - -**Output:** - -```python -[ - Device( - device_id="6ba7b811-9dad-11d1-80b4-00c04fd430c8", - display_name="Front Door", - can_program_online_access_codes=true, - ... - ), - ... -] -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -devices = seam.devices.list - -lock = devices.find(&:can_program_online_access_codes) -``` - -**Output:** - -```ruby -[ - { - "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name" => "Front Door", - "can_program_online_access_codes" => true, - ... - }, - ... -] -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$devices = $seam->devices->list(); -``` - -**Output:** - -```php -[ - [ - "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name" => "Front Door", - "can_program_online_access_codes" => true, - ... - ], - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -*** - -## Create a User Identity - -You can create a user identity before creating the Access Grant, you can retrieve an existing user identity, or you can skip this step and create a new user identity as part of the Access Grant creation action. - -To create a user identity, specify the unique `user_identity_key`, `email_address`, or `phone_number` of the user. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.userIdentities.create({ - full_name: "Jane Doe", - email_address: "jane@example.com", -}); -``` - -**Output:** - -```json -{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... -} -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/user_identities/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "full_name": "Jane Doe", - "email_address": "jane@example.com" -}' -``` - -**Output:** - -```json -{ - "user_identity": { - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... - } -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.user_identities.create( - full_name="Jane Doe", - email_address="jane@example.com" -) -``` - -**Output:** - -```python -UserIdentity( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - full_name="Jane Doe", - email_address="jane@example.com", - ... -) -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.user_identities.create( - full_name: "Jane Doe", - email_address: "jane@example.com", -) -``` - -**Output:** - -```ruby -{ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -} -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->user_identities->create( - full_name: "Jane Doe", - email_address: "jane@example.com" -); -``` - -**Output:** - -```php -[ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -*** - -## Create an Access Grant - -To create an Access Grant, specify the user identity, device IDs, starting and ending times, and requested access methods, such as `code`. - -To grant access to multiple devices at the same time, include all the desired device IDs in the `device_ids` array. Seam creates the requested access methods on each device. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.accessGrants.create({ - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - device_ids: [ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8" - ], - requested_access_methods: [ - {"mode": "code"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -}); -``` - -**Output:** - -```json -{ - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... -} -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```bash -# Alternately, to create a new user identity, use the -# following parameter instead of user_identity_id: -# user_identity={ -# "full_name": "Jane Doe", -# "email_address": "jane.doe@example.com", -# }, -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "device_ids": [ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8" - ], - "requested_access_methods": [ - {"mode": "code"} - ], - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z" -}' -``` - -**Output:** - -```json -{ - "access_grant": { - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... - } -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.access_grants.create( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity={ - # "full_name": "Jane Doe", - # "email_address": "jane.doe@example.com", - # }, - device_ids=[ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8" - ], - requested_access_methods=[ - {"mode": "code"} - ], - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z" -) -``` - -**Output:** - -```python -AccessGrant( - access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - display_name="My Access Grant", - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z", - requested_access_methods=[ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... -) -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.access_grants.create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity: { - # full_name: "Jane Doe", - # email_address: "jane.doe@example.com", - # }, - device_ids: %w[6ba7b811-9dad-11d1-80b4-00c04fd430c8], - requested_access_methods: [ - {"mode": "code"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -) -``` - -**Output:** - -```ruby -{ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "requested_access_methods" => [ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... -} -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->access_grants->create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - device_ids: [ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - ], - requested_access_methods: [ - ["mode" => "code"], - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -); -``` - -**Output:** - -```php -[ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "requested_access_methods" => [ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -*** - -## Retrieve the Access Methods - -Once an access method has been issued, retrieve it by ID. For a `code` access method, the returned access method includes the `code` that you can deliver to your user. - -You can poll the access method for the `is_issued` status change or watch for the `access_method.issued` event. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.accessMethods.get({ - access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" -}); -``` - -**Output:** - -```json -{ - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name": "PIN Code", - "mode": "code", - "is_issued": true, - "code": "1234", - ... -} -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" -}' -``` - -**Output:** - -```json -{ - "access_method": { - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name": "PIN Code", - "mode": "code", - "is_issued": true, - "code": "1234", - ... - }, - "ok": true -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.access_methods.get( - access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479" -) -``` - -**Output:** - -```python -AccessMethod( - access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", - display_name="PIN Code", - mode="code", - is_issued=true, - code="1234", - ... -) -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.access_methods.get( - access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" -) -``` - -**Output:** - -```ruby -{ - "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name" => "PIN Code", - "mode" => "code", - "is_issued" => true, - "code" => "1234", - ... -} -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->access_methods->get( - access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" -); -``` - -**Output:** - -```php -[ - "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name" => "PIN Code", - "mode" => "code", - "is_issued" => true, - "code" => "1234", - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -*** - -## Next Steps - -Once you've created the Access Grant and the resulting access methods have been issued, you can deliver the access methods to your user. For details, see [Delivering Access Methods](delivering-access-methods.md). - -To organize devices into logical groups—for example, all the locks that a guest staying in Unit 101 needs—and grant access to the whole group with a single ID, see [Creating an Access Grant Using Spaces](creating-an-access-grant-using-spaces.md). diff --git a/docs/guides/use-cases/granting-access/creating-an-access-grant-using-entrances.md b/docs/guides/use-cases/granting-access/creating-an-access-grant-using-entrances.md deleted file mode 100644 index a0a38a012..000000000 --- a/docs/guides/use-cases/granting-access/creating-an-access-grant-using-entrances.md +++ /dev/null @@ -1,913 +0,0 @@ ---- -description: >- - Learn how to create an access grant to define the "who, where, when, and how" - for assigning a user access to entrances. ---- - -# Creating an Access Grant Using Entrances - -An Access Grant defines the following characteristics: - -* User identity: The user to whom you want to grant access. -* Entrances: The set of entrances or other access points to which you want to grant the user access. -* Access schedule: The starting and ending times for access. -* Access methods: The modes of access, including key cards, PIN codes, mobile keys, and [Instant Keys](../../capability-guides/instant-keys/). - -It is important to note that you can specify the set of entrances to which you want to grant access using the IDs of the entrances themselves. Alternately, before creating an Access Grant, you can organize sets of entrances into spaces. Then, when you create an Access Grant, you specify the IDs of the spaces to which you want to grant access. Seam grants the user access to all entrances included in these spaces. - -This topic describes how to create an Access Grant using entrances. To learn how to create an Access Grant using spaces, see [Creating an Access Grant Using Spaces](creating-an-access-grant-using-spaces.md). - -*** - -## Access Grant Creation Process - -To create an Access Grant: - -1. [Identify the entrances](creating-an-access-grant-using-entrances.md#identify-entrances) to which you want to grant the user access. -2. [Create a user identity](creating-an-access-grant-using-entrances.md#create-a-user-identity) for the user to whom you want to grant access. Alternately, you can create a new user identity as part of the Access Grant creation action. -3. [Create an Access Grant](creating-an-access-grant-using-entrances.md#create-an-access-grant) for the user identity to define the entrances to which the user should have access, the starting and ending times for this access, and the requested access methods, that is, one or more of `card`, `code`, and `mobile_key`. - - The action returns the created Access Grant. -4. [Monitor for lifecycle events](creating-an-access-grant-using-entrances.md#monitor-for-lifecycle-events) to identify next steps, such as the following: - * Whether you need to encode a card access method onto a plastic card. - * When the access methods are ready to deliver to your user. - -If you've created an Access Grant that includes an mobile key, the returned Access Grant includes the Instant Key URL. to make it more efficient for you to share this URL with your user. - -*** - -## Before You Begin - -To create an Access Grant, first [connect](../../core-concepts/workspaces/#connecting-virtual-devices) an access system to Seam. You may also need to set up your access system and confirm that it has the required licenses. For details, see [Setting Up Your Site for Instant Keys](../../capability-guides/instant-keys/setting-up-your-site-for-instant-keys.md) and the [system integration guide](https://docs.seam.co/latest/device-and-system-integration-guides#access-control-systems) for your access system. - -*** - -## **Identify Entrances** - -List the entrances in the access system and identify the ones to which you want to grant the user access. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.acs.entrances.list({ - acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339", -}); -``` - -**Output:** - -```json -[ - { - "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name": "Main Entrance", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - { - "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc", - "display_name": "Room 101", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - ... -] -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/acs/entrances/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" -}' -``` - -**Output:** - -```json -{ - "acs_entrances": [ - { - "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name": "Main Entrance", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - { - "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc", - "display_name": "Room 101", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - ... - ] -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.acs.entrances.list( - acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" -) -``` - -**Output:** - -```python -[ - AcsEntrance( - acs_entrance_id="48ebfb50-c531-43c5-b9ea-409f26dabbd7", - display_name="Main Entrance", - acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ), - AcsEntrance( - acs_entrance_id="f74e4879-5991-4e2f-a368-888983dcfbfc", - display_name="Room 101", - acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ), - ... -] -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.acs.entrances.list( - acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" -) -``` - -**Output:** - -```json -[ - { - "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name" => "Main Entrance", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - { - "acs_entrance_id" => "f74e4879-5991-4e2f-a368-888983dcfbfc", - "display_name" => "Room 101", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - ... -] -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->acs->entrances->list( - acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" -); -``` - -**Output:** - -```php -[ - [ - "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name" => "Main Entrance", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ], - [ - "acs_entrance_id" => "f74e4879-5991-4e2f-a368-888983dcfbfc", - "display_name" => "Room 101", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ], - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -## **Create a User Identity** - -You can create a user identity before creating the Access Grant, you can retrieve an existing user identity, or you can skip this step and [create a new user identity as part of the Access Grant creation action](creating-an-access-grant-using-entrances.md#create-an-access-grant). - -To create a user identity, specify the unique `user_identity_key`, `email_address`, or `phone_number` of the user. Also, include the ID of the access system in which you want to grant the user access. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.userIdentities.create({ - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], -}); -``` - -**Output:** - -```json -{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... -} -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```curl -curl -X 'POST' \ - 'https://connect.getseam.com/user_identities/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "full_name": "Jane Doe", - "email_address": "jane@example.com", - "acs_system_ids": [ - "c359cba2-8ef2-47fc-bee0-1c7c2a886339" - ] -}' -``` - -**Output:** - -```json -{ - "user_identity": { - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... - } -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.user_identities.create( - full_name="Jane Doe", - email_address="jane@example.com", - acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -) -``` - -**Output:** - -```python -UserIdentity( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - full_name="Jane Doe", - email_address="jane@example.com", - ... -) -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.user_identities.create( - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], -) -``` - -**Output:** - -```ruby -{ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -} -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->user_identities->create( - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -); -``` - -**Output:** - -```php -[ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -*** - -## **Create an Access Grant** - -To create an Access Grant, specify the user identity, entrance IDs, starting and ending times, and requested access methods, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, specify `mobile_key` as the mode for a requested access method. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.accessGrants.create({ - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - acs_entrance_ids: [ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc" - ], - requested_access_methods: [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -}); -``` - -**Output:** - -```json -{ - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... -} -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```curl -# Alternately, to create a new user identity, use the -# following parameter instead of user_identity_id: -# user_identity={ -# "full_name": "Jane Doe", -# "email_address": "jane.doe@example.com", -# }, -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "acs_entrance_ids": [ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc" - ], - "requested_access_methods": [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z" -}' -``` - -**Output:** - -```json -{ - "access_grant": { - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key Credential", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... - } -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.access_grants.create( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity={ - # "full_name": "Jane Doe", - # "email_address": "jane.doe@example.com", - # }, - acs_entrance_ids=[ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc" - ], - requested_access_methods=[ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z" -) -``` - -**Output:** - -```python -AccessGrant( - access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - display_name="My Access Grant", - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z", - requested_access_methods=[ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - instant_key_url="https://ik.seam.co/ABCXYZ", - ... -) -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.access_grants.create( - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity: { - # full_name: "Jane Doe", - # email_address: "jane.doe@example.com", - # }, - acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc], - requested_access_methods: [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -) -``` - -**Output:** - -```ruby -{ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "requested_access_methods" => [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -} -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->access_grants->create( - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - acs_entrance_ids: [ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc", - ], - requested_access_methods: [ - ["mode" => "code"], - ["mode" => "card"], - ["mode" => "mobile_key"], - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -); -``` - -**Output:** - -```php -[ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "requested_access_methods" => [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -*** - -## Poll for Status Changes or Monitor for Lifecycle Events - -Once you've created an Access Grant with one or more access methods, poll the created access methods for status changes or watch for Access Grant and access method lifecycle events. The `access_method.is_issued` property and event let you know when an access method is ready to deliver to your user. - -### Poll for Status Changes - -To poll the created access methods, get these access methods by ID and look for the following status changes: - -* If `access_method.is_encoding_required` is `true`, you must encode the card access method onto a plastic key card. Once you've encoded the access method onto a card, this property changes to `false`. -* When an access method is ready to be delivered to a user, `access_method.is_issued` changes to `true`. For a card access method, `access_method.is_issued` changes to `true` after you encode the plastic card. You can also view the `access_method.issued_at` property to learn when the access method was issued. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.accessMethods.get({ - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -}); -``` - -**Output:** - -```json -{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... -} -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -}' -``` - -**Output:** - -```json -{ - "access_method": { - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... - }, - "ok": true -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.access_methods.get( - access_method_id = "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -**Output:** - -``` -AccessMethod( - access_method_id="c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - display_name="Plastic Card", - mode="card", - created_at="2025-06-16T16:54:19.946606Z", - is_card_encoding_required=true, - is_issued=false, - issued_at=null, - ... -) -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.access_methods.get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -**Output:** - -``` -{ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -} -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->access_methods->get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -); -``` - -**Output:** - -```json -[ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -### Monitor for Lifecycle Events - -Watch for the following Access Grant and access method events that include the IDs of the created Access Grant and access methods: - -* `access_grant.access_granted_to_door` -* `access_grant.access_granted_to_all_doors` -* `access_method.card_encoding_required` -* `access_method.issued` - -These events tell you what to do next. For example, if you've created a card access method, `access_method.card_encoding_required` lets you know that you need to encode the access method onto a plastic card. `access_grant.access_granted_to_all_doors` tells you that Seam has successfully created all the access methods that you requested through an Access Grant. `access_method.issued` indicates that you can now deliver the access method to your user. - -The following example shows the payload for an `access_method.card_encoding_required` event: - -```json -{ - "event_id": "22222222-3333-4444-5555-666666666666", - "event_description": "An access method representing a physical card requires encoding.", - "event_type": "access_method.card_encoding_required", - "acs_system_id": "11111111-1111-1111-1111-111111111111", - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - ... -} -``` - -*** - -## Next Steps - -Once you've created the Access Grant and the resulting access methods have been issued, you can deliver the access methods to your user. For details, see [Delivering Access Methods](delivering-access-methods.md). diff --git a/docs/guides/use-cases/granting-access/creating-an-access-grant-using-spaces.md b/docs/guides/use-cases/granting-access/creating-an-access-grant-using-spaces.md deleted file mode 100644 index fb312feef..000000000 --- a/docs/guides/use-cases/granting-access/creating-an-access-grant-using-spaces.md +++ /dev/null @@ -1,936 +0,0 @@ ---- -description: >- - Learn how to create an Access Grant to define the "who, where, when, and how" - for assigning a user access to entrances grouped into spaces. ---- - -# Creating an Access Grant Using Spaces - -An Access Grant defines the following characteristics: - -* User identity: The user to whom you want to grant access. -* Entrances or spaces: The sets of entrances or other access points to which you want to grant the user access. -* Access schedule: The starting and ending times for access. -* Access methods: The modes of access, including key cards, PIN codes, mobile keys, and [Instant Keys](../../capability-guides/instant-keys/). - -Before creating an Access Grant, you can organize sets of entrances into [spaces](https://docs.seam.co/latest/api/spaces/). Then, when you create an Access Grant, you specify the IDs of the spaces to which you want to grant access. Seam grants the user access to all entrances included in these spaces. Alternately, you can specify the set of entrances to which you want to grant access using the IDs of the entrances themselves. - -This topic describes how to create an Access Grant using spaces. To learn how to create an Access Grant using entrances, see [Creating an Access Grant Using Entrances](creating-an-access-grant-using-entrances.md). - -*** - -## Access Grant Creation Process - -To create an Access Grant: - -1. [Identify the spaces](creating-an-access-grant-using-spaces.md#identify-space) to which you want to grant the user access. -2. [Create a user identity](creating-an-access-grant-using-spaces.md#create-a-user-identity) for the user to whom you want to grant access. Alternately, you can create a new user identity as part of the Access Grant creation action. -3. [Create an access grant](creating-an-access-grant-using-spaces.md#create-an-access-grant) for the user identity to define the entrances to which the user should have access, the starting and ending times for this access, and the requested access methods, that is, one or more of `card`, `code`, and `mobile_key`. - - The action returns the created Access Grant. -4. [Poll for status changes or monitor for lifecycle events](creating-an-access-grant-using-spaces.md#poll-for-status-changes-or-monitor-for-lifecycle-events) to identify next steps, such as the following: - * Whether you need to encode a card access method onto a plastic card. - * When the access methods are ready to deliver to your user. - -If you've created an Access Grant that includes an mobile key, the returned Access Grant includes the Instant Key URL. to make it more efficient for you to share this URL with your user. - -*** - -## Before You Begin - -To create an Access Grant, first [connect](../../core-concepts/workspaces/#connecting-virtual-devices) an access system to Seam. You may also need to set up your access system and confirm that it has the required licenses. For details, see [Setting Up Your Site for Instant Keys](../../capability-guides/instant-keys/setting-up-your-site-for-instant-keys.md) and the [system integration guide](https://docs.seam.co/latest/device-and-system-integration-guides#access-control-systems) for your access system. - -Create one or more spaces to group the entrances to which you want to grant access. For details, see [Spaces](https://docs.seam.co/latest/api/spaces/) and [Create a Space](https://docs.seam.co/latest/api/spaces/create). - -*** - -## **Identify Spaces** - -List the spaces and identify the ones to which you want to grant the user access. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.spaces.list(); -``` - -**Output:** - -```json -[ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -] -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/spaces/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -**Output:** - -```json -{ - "spaces": [ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... - ], - ok: true -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.spaces.list() -``` - -**Output:** - -```python -[ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -] -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.spaces.list() -``` - -**Output:** - -```json -[ - { - "created_at" => "2025-06-16T16:54:17.946600Z", - "display_name" => "Room 101", - "name" => "Room 101", - "space_id" => "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at" => "2025-06-16T16:55:31.429200Z", - "display_name" => "Common Doors", - "name" => "Common Doors", - "space_id" => "550e8400-e29b-41d4-a716-446655440000", - "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -] -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->spaces->list(); -``` - -**Output:** - -```php -[ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -## **Create a User Identity** - -You can create a user identity before creating the Access Grant, you can retrieve an existing user identity, or you can skip this step and [create a new user identity as part of the Access Grant creation action](creating-an-access-grant-using-spaces.md#create-an-access-grant). - -To create a user identity, specify the unique `user_identity_key`, `email_address`, or `phone_number` of the user. Also, include the ID of the access system in which you want to grant the user access. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.userIdentities.create({ - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], -}); -``` - -**Output:** - -```json -{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... -} -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```curl -curl -X 'POST' \ - 'https://connect.getseam.com/user_identities/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "full_name": "Jane Doe", - "email_address": "jane@example.com", - "acs_system_ids": [ - "c359cba2-8ef2-47fc-bee0-1c7c2a886339" - ] -}' -``` - -**Output:** - -```json -{ - "user_identity": { - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... - } -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.user_identities.create( - full_name="Jane Doe", - email_address="jane@example.com", - acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -) -``` - -**Output:** - -```python -UserIdentity( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - full_name="Jane Doe", - email_address="jane@example.com", - ... -) -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.user_identities.create( - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], -) -``` - -**Output:** - -```ruby -{ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -} -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->user_identities->create( - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -); -``` - -**Output:** - -```php -[ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -*** - -## **Create an Access Grant** - -To create an Access Grant, specify the user identity, entrance IDs, starting and ending times, and requested access methods, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, specify `mobile_key` as the mode for a requested access method. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.accessGrants.create({ - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - space_ids: [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - requested_access_methods: [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -}); -``` - -**Output:** - -```json -{ - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "space_ids": [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods": [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... -} -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```curl -# Alternately, to create a new user identity, use the -# following parameter instead of user_identity_id: -# user_identity={ -# "full_name": "Jane Doe", -# "email_address": "jane.doe@example.com", -# }, -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "space_ids": [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods": [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z" -}' -``` - -**Output:** - -```json -{ - "access_grant": { - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "space_ids": [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods": [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key Credential", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... - } -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.access_grants.create( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity={ - # "full_name": "Jane Doe", - # "email_address": "jane.doe@example.com", - # }, - space_ids=[ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - requested_access_methods=[ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z" -) -``` - -**Output:** - -```python -AccessGrant( - access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - display_name="My Access Grant", - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z", - space_ids=[ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - requested_access_methods=[ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - instant_key_url="https://ik.seam.co/ABCXYZ", - ... -) -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.access_grants.create( - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity: { - # full_name: "Jane Doe", - # email_address: "jane.doe@example.com", - # }, - space_ids: %w[5afeb047-3277-4102-b8c4-99edf05b91d2 550e8400-e29b-41d4-a716-446655440000], - requested_access_methods: [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -) -``` - -**Output:** - -```ruby -{ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "space_ids" => [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods" => [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -} -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->access_grants->create( - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - space_ids: [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - requested_access_methods: [ - ["mode" => "code"], - ["mode" => "card"], - ["mode" => "mobile_key"], - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -); -``` - -**Output:** - -```php -[ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "space_ids" => [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods" => [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -*** - -## Poll for Status Changes or Monitor for Lifecycle Events - -Once you've created an Access Grant with one or more access methods, poll the created access methods for status changes or watch for Access Grant and access method lifecycle events. The `access_method.is_issued` property and event let you know when an access method is ready to deliver to your user. - -### Poll for Status Changes - -To poll the created access methods, get these access methods by ID and look for the following status changes: - -* If `access_method.is_encoding_required` is `true`, you must encode the card access method onto a plastic key card. Once you've encoded the access method onto a card, this property changes to `false`. -* When an access method is ready to be delivered to a user, `access_method.is_issued` changes to `true`. For a card access method, `access_method.is_issued` changes to `true` after you encode the plastic card. You can also view the `access_method.issued_at` property to learn when the access method was issued. - -{% tabs %} -{% tab title="JavaScript" %} - -**Code:** - -```javascript -await seam.accessMethods.get({ - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -}); -``` - -**Output:** - -```json -{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... -} -``` -{% endtab %} - -{% tab title="cURL" %} - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -}' -``` - -**Output:** - -```json -{ - "access_method": { - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... - }, - "ok": true -} -``` -{% endtab %} - -{% tab title="Python" %} - -**Code:** - -```python -seam.access_methods.get( - access_method_id = "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -**Output:** - -``` -AccessMethod( - access_method_id="c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - display_name="Plastic Card", - mode="card", - created_at="2025-06-16T16:54:19.946606Z", - is_card_encoding_required=true, - is_issued=false, - issued_at=null, - ... -) -``` -{% endtab %} - -{% tab title="Ruby" %} - -**Code:** - -```ruby -seam.access_methods.get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -**Output:** - -``` -{ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -} -``` -{% endtab %} - -{% tab title="PHP" %} - -**Code:** - -```php -$seam->access_methods->get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -); -``` - -**Output:** - -```json -[ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -]; -``` -{% endtab %} - -{% tab title="C#" %} - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` -{% endtab %} -{% endtabs %} - -### Monitor for Lifecycle Events - -Watch for the following Access Grant and access method events that include the IDs of the created Access Grant and access methods: - -* `access_grant.access_granted_to_door` -* `access_grant.access_granted_to_all_doors` -* `access_method.card_encoding_required` -* `access_method.issued` - -These events tell you what to do next. For example, if you've created a card access method, `access_method.card_encoding_required` lets you know that you need to encode the access method onto a plastic card. `access_grant.access_granted_to_all_doors` tells you that Seam has successfully created all the access methods that you requested through an Access Grant. `access_method.issued` indicates that you can now deliver the access method to your user. - -The following example shows the payload for an `access_method.card_encoding_required` event: - -```json -{ - "event_id": "22222222-3333-4444-5555-666666666666", - "event_description": "An access method representing a physical card requires encoding.", - "event_type": "access_method.card_encoding_required", - "acs_system_id": "11111111-1111-1111-1111-111111111111", - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - ... -} -``` - -*** - -## Next Steps - -Once you've created the Access Grant and the resulting access methods have been issued, you can deliver the access methods to your user. For details, see [Delivering Access Methods](delivering-access-methods.md). diff --git a/docs/guides/use-cases/granting-access/creating-an-access-grant.md b/docs/guides/use-cases/granting-access/creating-an-access-grant.md new file mode 100644 index 000000000..5b75afb3d --- /dev/null +++ b/docs/guides/use-cases/granting-access/creating-an-access-grant.md @@ -0,0 +1,1435 @@ +--- +description: >- + Learn how to create an Access Grant to define the "who, where, when, and how" + for assigning a user access to devices, spaces, or entrances. +--- + +# Creating an Access Grant + +An Access Grant defines the following characteristics: + +- **User identity:** The user to whom you want to grant access. +- **Resources:** The set of devices, spaces, or entrances to which you want to grant the user access. +- **Access schedule:** The starting and ending times for access. +- **Access methods:** The modes of access, such as PIN codes, key cards, mobile keys, and [Instant Keys](../../capability-guides/instant-keys/). + +You specify which resources to grant access to using one of three parameters: + +| Parameter | Use case | Description | +| --- | --- | --- | +| `device_ids` | Standalone smart locks | Pass the IDs of individual devices, such as August, Yale, Schlage, igloohome, or TTLock locks connected through a [Connect Webview](../../core-concepts/connect-webviews/). | +| `space_ids` | Grouped access points | Organize entrances and devices into [spaces](https://docs.seam.co/latest/api/spaces/) first, then grant access to entire spaces. Useful for giving a guest access to everything they need (room door, main entrance, elevator) with one call. | +| `acs_entrance_ids` | Access control system entrances | Pass the IDs of individual ACS entrances. Use this when you want fine-grained control over which entrances to include. | + +You can also combine these parameters in a single Access Grant. + +*** + +## Access Grant Creation Process + +To create an Access Grant: + +1. [Identify your resources](#identify-your-resources)—the devices, spaces, or entrances to which you want to grant access. +2. [Create a user identity](#create-a-user-identity) for the user to whom you want to grant access. You can also create a new user identity as part of the Access Grant creation. +3. [Create an Access Grant](#create-an-access-grant) specifying the user identity, resources, access schedule, and requested access methods. +4. [Monitor for access method readiness](#monitor-for-access-method-readiness) to know when access methods are issued and ready to deliver. + +If you create an Access Grant that includes a mobile key, the returned Access Grant includes the Instant Key URL for efficient sharing. + +*** + +## Before You Begin + +**For standalone smart locks:** [Connect](../../core-concepts/connect-webviews/) the device account to Seam. Confirm that the device supports access codes by checking its `can_program_online_access_codes` capability flag. + +{% hint style="info" %} +You can try this entire flow in a [sandbox workspace](../../core-concepts/workspaces/#sandbox-workspaces) using sandbox devices, such as the August sandbox locks. +{% endhint %} + +**For access control systems (spaces or entrances):** [Connect](../../core-concepts/workspaces/#connecting-virtual-devices) your access system to Seam. You may also need to set up your access system and confirm that it has the required licenses. For details, see [Setting Up Your Site for Instant Keys](../../capability-guides/instant-keys/setting-up-your-site-for-instant-keys.md) and the [system integration guide](https://docs.seam.co/latest/device-and-system-integration-guides#access-control-systems) for your access system. + +If you want to use spaces, create them first. For details, see [Spaces](https://docs.seam.co/latest/api/spaces/) and [Create a Space](https://docs.seam.co/latest/api/spaces/create). + +*** + +## Identify Your Resources + +Depending on your setup, identify the devices, spaces, or entrances to which you want to grant access. + +### List Devices + +List your devices and check the `can_program_online_access_codes` capability flag. + +{% tabs %} +{% tab title="JavaScript" %} + +**Code:** + +```javascript +const devices = await seam.devices.list() + +const lock = devices.find((device) => device.can_program_online_access_codes) +``` + +**Output:** + +```json +[ + { + "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + "display_name": "Front Door", + "can_program_online_access_codes": true, + ... + }, + ... +] +``` + +{% endtab %} + +{% tab title="cURL" %} + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/devices/list' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{}' +``` + +**Output:** + +```json +{ + "devices": [ + { + "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + "display_name": "Front Door", + "can_program_online_access_codes": true, + ... + }, + ... + ] +} +``` + +{% endtab %} + +{% tab title="Python" %} + +**Code:** + +```python +devices = seam.devices.list() + +lock = next( + device for device in devices + if device.can_program_online_access_codes +) +``` + +**Output:** + +```python +[ + Device( + device_id="6ba7b811-9dad-11d1-80b4-00c04fd430c8", + display_name="Front Door", + can_program_online_access_codes=true, + ... + ), + ... +] +``` + +{% endtab %} + +{% tab title="Ruby" %} + +**Code:** + +```ruby +devices = seam.devices.list + +lock = devices.find(&:can_program_online_access_codes) +``` + +**Output:** + +```ruby +[ + { + "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + "display_name" => "Front Door", + "can_program_online_access_codes" => true, + ... + }, + ... +] +``` + +{% endtab %} + +{% tab title="PHP" %} + +**Code:** + +```php +$devices = $seam->devices->list(); +``` + +**Output:** + +```php +[ + [ + "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + "display_name" => "Front Door", + "can_program_online_access_codes" => true, + ... + ], + ... +]; +``` + +{% endtab %} + +{% tab title="C#" %} + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + +{% endtab %} +{% endtabs %} + +### List Spaces + +List the spaces and identify the ones to which you want to grant access. + +{% tabs %} +{% tab title="JavaScript" %} + +**Code:** + +```javascript +await seam.spaces.list() +``` + +**Output:** + +```json +[ + { + "created_at": "2025-06-16T16:54:17.946600Z", + "display_name": "Room 101", + "name": "Room 101", + "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + { + "created_at": "2025-06-16T16:55:31.429200Z", + "display_name": "Common Doors", + "name": "Common Doors", + "space_id": "550e8400-e29b-41d4-a716-446655440000", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + ... +] +``` + +{% endtab %} + +{% tab title="cURL" %} + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/spaces/list' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{}' +``` + +**Output:** + +```json +{ + "spaces": [ + { + "created_at": "2025-06-16T16:54:17.946600Z", + "display_name": "Room 101", + "name": "Room 101", + "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + { + "created_at": "2025-06-16T16:55:31.429200Z", + "display_name": "Common Doors", + "name": "Common Doors", + "space_id": "550e8400-e29b-41d4-a716-446655440000", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + ... + ], + "ok": true +} +``` + +{% endtab %} + +{% tab title="Python" %} + +**Code:** + +```python +seam.spaces.list() +``` + +**Output:** + +```python +[ + { + "created_at": "2025-06-16T16:54:17.946600Z", + "display_name": "Room 101", + "name": "Room 101", + "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + ... +] +``` + +{% endtab %} + +{% tab title="Ruby" %} + +**Code:** + +```ruby +seam.spaces.list() +``` + +**Output:** + +```json +[ + { + "created_at" => "2025-06-16T16:54:17.946600Z", + "display_name" => "Room 101", + "name" => "Room 101", + "space_id" => "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + ... +] +``` + +{% endtab %} + +{% tab title="PHP" %} + +**Code:** + +```php +$seam->spaces->list(); +``` + +**Output:** + +```php +[ + [ + "created_at" => "2025-06-16T16:54:17.946600Z", + "display_name" => "Room 101", + "name" => "Room 101", + "space_id" => "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" + ], + ... +]; +``` + +{% endtab %} + +{% tab title="C#" %} + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + +{% endtab %} +{% endtabs %} + +### List Entrances + +List the entrances in your access system and identify the ones to which you want to grant access. + +{% tabs %} +{% tab title="JavaScript" %} + +**Code:** + +```javascript +await seam.acs.entrances.list({ + acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', +}) +``` + +**Output:** + +```json +[ + { + "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "display_name": "Main Entrance", + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + }, + { + "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc", + "display_name": "Room 101", + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + }, + ... +] +``` + +{% endtab %} + +{% tab title="cURL" %} + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/acs/entrances/list' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +}' +``` + +**Output:** + +```json +{ + "acs_entrances": [ + { + "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "display_name": "Main Entrance", + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + }, + ... + ] +} +``` + +{% endtab %} + +{% tab title="Python" %} + +**Code:** + +```python +seam.acs.entrances.list( + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) +``` + +**Output:** + +```python +[ + AcsEntrance( + acs_entrance_id="48ebfb50-c531-43c5-b9ea-409f26dabbd7", + display_name="Main Entrance", + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + ), + ... +] +``` + +{% endtab %} + +{% tab title="Ruby" %} + +**Code:** + +```ruby +seam.acs.entrances.list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) +``` + +**Output:** + +```json +[ + { + "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "display_name" => "Main Entrance", + "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + }, + ... +] +``` + +{% endtab %} + +{% tab title="PHP" %} + +**Code:** + +```php +$seam->acs->entrances->list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); +``` + +**Output:** + +```php +[ + [ + "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "display_name" => "Main Entrance", + "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + ], + ... +]; +``` + +{% endtab %} + +{% tab title="C#" %} + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + +{% endtab %} +{% endtabs %} + +*** + +## Create a User Identity + +You can create a user identity before creating the Access Grant, retrieve an existing one, or create a new user identity as part of the Access Grant creation action. + +To create a user identity, specify the unique `user_identity_key`, `email_address`, or `phone_number` of the user. If you are granting access to an access control system, also include the `acs_system_ids`. + +{% tabs %} +{% tab title="JavaScript" %} + +**Code:** + +```javascript +await seam.userIdentities.create({ + full_name: 'Jane Doe', + email_address: 'jane@example.com', + // Include acs_system_ids if granting access to an ACS: + // acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], +}) +``` + +**Output:** + +```json +{ + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "full_name": "Jane Doe", + "email_address": "jane@example.com", + ... +} +``` + +{% endtab %} + +{% tab title="cURL" %} + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/user_identities/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "full_name": "Jane Doe", + "email_address": "jane@example.com" +}' +``` + +**Output:** + +```json +{ + "user_identity": { + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "full_name": "Jane Doe", + "email_address": "jane@example.com", + ... + } +} +``` + +{% endtab %} + +{% tab title="Python" %} + +**Code:** + +```python +seam.user_identities.create( + full_name="Jane Doe", + email_address="jane@example.com" + # Include acs_system_ids if granting access to an ACS: + # acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] +) +``` + +**Output:** + +```python +UserIdentity( + user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", + full_name="Jane Doe", + email_address="jane@example.com", + ... +) +``` + +{% endtab %} + +{% tab title="Ruby" %} + +**Code:** + +```ruby +seam.user_identities.create( + full_name: "Jane Doe", + email_address: "jane@example.com", + # Include acs_system_ids if granting access to an ACS: + # acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], +) +``` + +**Output:** + +```ruby +{ + "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", + "full_name" => "Jane Doe", + "email_address" => "jane@example.com", + ... +} +``` + +{% endtab %} + +{% tab title="PHP" %} + +**Code:** + +```php +$seam->user_identities->create( + full_name: "Jane Doe", + email_address: "jane@example.com" + // Include acs_system_ids if granting access to an ACS: + // acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] +); +``` + +**Output:** + +```php +[ + "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", + "full_name" => "Jane Doe", + "email_address" => "jane@example.com", + ... +]; +``` + +{% endtab %} + +{% tab title="C#" %} + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + +{% endtab %} +{% endtabs %} + +*** + +## Create an Access Grant + +Specify the user identity, resources, access schedule, and requested access methods. The examples below show each resource type. + +{% hint style="info" %} +You can also create a new user identity inline by passing `user_identity` (with `full_name` and `email_address`) instead of `user_identity_id`. +{% endhint %} + +### Using Device IDs + +Use `device_ids` for standalone smart locks. To grant access to multiple devices, include all the desired device IDs in the array. + +{% tabs %} +{% tab title="JavaScript" %} + +**Code:** + +```javascript +await seam.accessGrants.create({ + user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', + device_ids: ['6ba7b811-9dad-11d1-80b4-00c04fd430c8'], + requested_access_methods: [{ mode: 'code' }], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` + +**Output:** + +```json +{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "display_name": "My Access Grant", + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z", + "requested_access_methods": [ + { + "display_name": "PIN Code", + "mode": "code", + "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], + ... + } + ], + ... +} +``` + +{% endtab %} + +{% tab title="cURL" %} + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "device_ids": [ + "6ba7b811-9dad-11d1-80b4-00c04fd430c8" + ], + "requested_access_methods": [ + {"mode": "code"} + ], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + +**Output:** + +```json +{ + "access_grant": { + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ... + } +} +``` + +{% endtab %} + +{% tab title="Python" %} + +**Code:** + +```python +seam.access_grants.create( + user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", + device_ids=[ + "6ba7b811-9dad-11d1-80b4-00c04fd430c8" + ], + requested_access_methods=[ + {"mode": "code"} + ], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z" +) +``` + +{% endtab %} + +{% tab title="Ruby" %} + +**Code:** + +```ruby +seam.access_grants.create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + device_ids: %w[6ba7b811-9dad-11d1-80b4-00c04fd430c8], + requested_access_methods: [ + {"mode": "code"} + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` + +{% endtab %} + +{% tab title="PHP" %} + +**Code:** + +```php +$seam->access_grants->create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + device_ids: [ + "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + ], + requested_access_methods: [ + ["mode" => "code"], + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` + +{% endtab %} + +{% tab title="C#" %} + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + +{% endtab %} +{% endtabs %} + +### Using Space IDs + +Use `space_ids` to grant access to all entrances in one or more spaces. You can request multiple access method modes, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, include `mobile_key`. + +{% tabs %} +{% tab title="JavaScript" %} + +**Code:** + +```javascript +await seam.accessGrants.create({ + user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', + space_ids: [ + '5afeb047-3277-4102-b8c4-99edf05b91d2', + '550e8400-e29b-41d4-a716-446655440000', + ], + requested_access_methods: [ + { mode: 'code' }, + { mode: 'card' }, + { mode: 'mobile_key' }, + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` + +**Output:** + +```json +{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "display_name": "My Access Grant", + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z", + "space_ids": [ + "5afeb047-3277-4102-b8c4-99edf05b91d2", + "550e8400-e29b-41d4-a716-446655440000" + ], + "requested_access_methods": [ + { + "display_name": "PIN Code", + "mode": "code", + ... + }, + { + "display_name": "Plastic Card", + "mode": "card", + ... + }, + { + "display_name": "Mobile Key", + "mode": "mobile_key", + ... + } + ], + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... +} +``` + +{% endtab %} + +{% tab title="cURL" %} + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "space_ids": [ + "5afeb047-3277-4102-b8c4-99edf05b91d2", + "550e8400-e29b-41d4-a716-446655440000" + ], + "requested_access_methods": [ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + +**Output:** + +```json +{ + "access_grant": { + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ... + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... + } +} +``` + +{% endtab %} + +{% tab title="Python" %} + +**Code:** + +```python +seam.access_grants.create( + user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", + space_ids=[ + "5afeb047-3277-4102-b8c4-99edf05b91d2", + "550e8400-e29b-41d4-a716-446655440000" + ], + requested_access_methods=[ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z" +) +``` + +{% endtab %} + +{% tab title="Ruby" %} + +**Code:** + +```ruby +seam.access_grants.create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + space_ids: %w[5afeb047-3277-4102-b8c4-99edf05b91d2 550e8400-e29b-41d4-a716-446655440000], + requested_access_methods: [ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` + +{% endtab %} + +{% tab title="PHP" %} + +**Code:** + +```php +$seam->access_grants->create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + space_ids: [ + "5afeb047-3277-4102-b8c4-99edf05b91d2", + "550e8400-e29b-41d4-a716-446655440000" + ], + requested_access_methods: [ + ["mode" => "code"], + ["mode" => "card"], + ["mode" => "mobile_key"], + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` + +{% endtab %} + +{% tab title="C#" %} + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + +{% endtab %} +{% endtabs %} + +### Using Entrance IDs + +Use `acs_entrance_ids` to grant access to specific ACS entrances. You can request multiple access method modes, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, include `mobile_key`. + +{% tabs %} +{% tab title="JavaScript" %} + +**Code:** + +```javascript +await seam.accessGrants.create({ + user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', + acs_entrance_ids: [ + '48ebfb50-c531-43c5-b9ea-409f26dabbd7', + 'f74e4879-5991-4e2f-a368-888983dcfbfc', + ], + requested_access_methods: [ + { mode: 'code' }, + { mode: 'card' }, + { mode: 'mobile_key' }, + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` + +**Output:** + +```json +{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "display_name": "My Access Grant", + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z", + "requested_access_methods": [ + { + "display_name": "PIN Code", + "mode": "code", + ... + }, + { + "display_name": "Plastic Card", + "mode": "card", + ... + }, + { + "display_name": "Mobile Key", + "mode": "mobile_key", + ... + } + ], + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... +} +``` + +{% endtab %} + +{% tab title="cURL" %} + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "acs_entrance_ids": [ + "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "f74e4879-5991-4e2f-a368-888983dcfbfc" + ], + "requested_access_methods": [ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + +**Output:** + +```json +{ + "access_grant": { + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ... + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... + } +} +``` + +{% endtab %} + +{% tab title="Python" %} + +**Code:** + +```python +seam.access_grants.create( + user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", + acs_entrance_ids=[ + "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "f74e4879-5991-4e2f-a368-888983dcfbfc" + ], + requested_access_methods=[ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z" +) +``` + +{% endtab %} + +{% tab title="Ruby" %} + +**Code:** + +```ruby +seam.access_grants.create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc], + requested_access_methods: [ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` + +{% endtab %} + +{% tab title="PHP" %} + +**Code:** + +```php +$seam->access_grants->create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + acs_entrance_ids: [ + "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "f74e4879-5991-4e2f-a368-888983dcfbfc", + ], + requested_access_methods: [ + ["mode" => "code"], + ["mode" => "card"], + ["mode" => "mobile_key"], + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` + +{% endtab %} + +{% tab title="C#" %} + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + +{% endtab %} +{% endtabs %} + +*** + +## Monitor for Access Method Readiness + +Once you've created an Access Grant, monitor the resulting access methods to know when they are ready to deliver to your user. + +### Poll for Status Changes + +Get the access methods by ID and check the following properties: + +- `is_encoding_required`: If `true`, you must encode the card access method onto a plastic key card. See [Working with Card Encoders and Scanners](../../low-level-apis/access-systems/working-with-card-encoders-and-scanners/). +- `is_issued`: When `true`, the access method is ready to be delivered to your user. + +{% tabs %} +{% tab title="JavaScript" %} + +**Code:** + +```javascript +await seam.accessMethods.get({ + access_method_id: 'f47ac10b-58cc-4372-a567-0e02b2c3d479', +}) +``` + +**Output:** + +```json +{ + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name": "PIN Code", + "mode": "code", + "is_issued": true, + "code": "1234", + ... +} +``` + +{% endtab %} + +{% tab title="cURL" %} + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" +}' +``` + +**Output:** + +```json +{ + "access_method": { + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name": "PIN Code", + "mode": "code", + "is_issued": true, + "code": "1234", + ... + }, + "ok": true +} +``` + +{% endtab %} + +{% tab title="Python" %} + +**Code:** + +```python +seam.access_methods.get( + access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479" +) +``` + +**Output:** + +```python +AccessMethod( + access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", + display_name="PIN Code", + mode="code", + is_issued=true, + code="1234", + ... +) +``` + +{% endtab %} + +{% tab title="Ruby" %} + +**Code:** + +```ruby +seam.access_methods.get( + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" +) +``` + +**Output:** + +```ruby +{ + "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name" => "PIN Code", + "mode" => "code", + "is_issued" => true, + "code" => "1234", + ... +} +``` + +{% endtab %} + +{% tab title="PHP" %} + +**Code:** + +```php +$seam->access_methods->get( + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" +); +``` + +**Output:** + +```php +[ + "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name" => "PIN Code", + "mode" => "code", + "is_issued" => true, + "code" => "1234", + ... +]; +``` + +{% endtab %} + +{% tab title="C#" %} + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + +{% endtab %} +{% endtabs %} + +### Watch for Lifecycle Events + +You can also watch for the following Access Grant and access method events: + +- `access_grant.access_granted_to_door` — Seam has granted access to a specific door. +- `access_grant.access_granted_to_all_doors` — Seam has granted access to all requested doors. +- `access_method.card_encoding_required` — A card access method needs to be encoded onto a plastic card. +- `access_method.issued` — An access method is ready to deliver to your user. + +Example `access_method.card_encoding_required` event payload: + +```json +{ + "event_id": "22222222-3333-4444-5555-666666666666", + "event_description": "An access method representing a physical card requires encoding.", + "event_type": "access_method.card_encoding_required", + "acs_system_id": "11111111-1111-1111-1111-111111111111", + "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", + ... +} +``` + +*** + +## Next Steps + +Once you've created the Access Grant and the resulting access methods have been issued, deliver the access methods to your user. For details, see [Delivering Access Methods](delivering-access-methods.md). diff --git a/docs/guides/use-cases/granting-access/using-cloud-keys.md b/docs/guides/use-cases/granting-access/using-cloud-keys.md index d6bc663b1..0fe821a0d 100644 --- a/docs/guides/use-cases/granting-access/using-cloud-keys.md +++ b/docs/guides/use-cases/granting-access/using-cloud-keys.md @@ -698,7 +698,7 @@ The unlock is now recorded in the ACS audit trail as an entry by the user identi ## Next Steps - [Delivering Access Methods](delivering-access-methods.md) -- [Creating an Access Grant Using Entrances](creating-an-access-grant-using-entrances.md) +- [Creating an Access Grant](creating-an-access-grant.md) - [Retrieving Access Grants and Access Methods](retrieving-access-grants-and-access-methods.md) - [Access Grants API Reference](https://docs.seam.co/latest/api/access_grants) - [ACS Entrances API Reference](https://docs.seam.co/latest/api/acs/entrances) diff --git a/docs/guides/use-cases/granting-access/using-instant-keys.md b/docs/guides/use-cases/granting-access/using-instant-keys.md new file mode 100644 index 000000000..a04b4d083 --- /dev/null +++ b/docs/guides/use-cases/granting-access/using-instant-keys.md @@ -0,0 +1,209 @@ +--- +description: >- + Learn how to deliver Instant Keys — shareable unlock links that work without + an app download — through Access Grants. +--- + +# Using Instant Keys + +Instant Keys are the fastest way to give someone mobile access. When you create an Access Grant with a `mobile_key` access method, Seam automatically generates an Instant Key URL. Share this URL with your user through text, email, or your app. When they tap the link, they can unlock the door immediately — no app download required. + +Instant Keys use iOS App Clips and Android Instant Apps to provide a native unlock experience without requiring your user to install anything. + +Instant Keys are ideal for: + +- **Guest access** — Send a link to a short-term guest (hotel, vacation rental, coworking space). +- **Backup access** — Provide a fallback unlock method alongside a native mobile key in your app. +- **Quick onboarding** — Let users unlock immediately while they set up your full mobile app. + +## Before You Begin + +To use Instant Keys, you need: + +- A [Seam API key](https://console.seam.co) +- A connected ACS with BLE-capable lock hardware that supports mobile keys +- Mobile key licenses activated for your ACS (see [Setting Up Your Site for Instant Keys](../../capability-guides/instant-keys/setting-up-your-site-for-instant-keys.md)) +- A [user identity](../../capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities.md) representing the person who will receive the Instant Key +- An entrance that supports mobile keys (`can_unlock_with_mobile_key` is `true`) + +{% hint style="info" %} +Instant Keys are generated automatically when you create a mobile key access method. You do not need to request them separately. +{% endhint %} + +## Step 1: Create an Access Grant with a Mobile Key + +Create an [Access Grant](./) specifying `mobile_key` as the requested access method mode. The response includes an `instant_key_url` on the Access Grant itself — you can share it immediately without waiting for the access method to be issued. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const accessGrant = await seam.accessGrants.create({ + user_identity_id: '22222222-2222-2222-2222-222222222222', + acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'], + requested_access_methods: [ + { mode: 'mobile_key' } + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) + +console.log(accessGrant.instant_key_url) +// => "https://ik.seam.co/ABCXYZ" +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + "requested_access_methods": [{ "mode": "mobile_key" }], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +access_grant = seam.access_grants.create( + user_identity_id="22222222-2222-2222-2222-222222222222", + acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods=[{"mode": "mobile_key"}], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z", +) + +print(access_grant.instant_key_url) +# => "https://ik.seam.co/ABCXYZ" +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +access_grant = seam.access_grants.create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [{ mode: "mobile_key" }], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) + +puts access_grant.instant_key_url +# => "https://ik.seam.co/ABCXYZ" +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$accessGrant = $seam->access_grants->create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [["mode" => "mobile_key"]], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); + +echo $accessGrant->instant_key_url; +// => "https://ik.seam.co/ABCXYZ" +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var accessGrant = seam.AccessGrants.Create( + userIdentityId: "22222222-2222-2222-2222-222222222222", + acsEntranceIds: new List + { + "f74e4879-5991-4e2f-a368-888983dcfbfc" + }, + requestedAccessMethods: new List + { + new RequestedAccessMethod { Mode = "mobile_key" } + }, + startsAt: "2025-07-13T15:00:00.000Z", + endsAt: "2025-07-16T11:00:00.000Z" +); + +Console.WriteLine(accessGrant.InstantKeyUrl); +// => "https://ik.seam.co/ABCXYZ" +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var accessGrant = seam.accessGrants().create( + AccessGrantsCreateRequest.builder() + .userIdentityId("22222222-2222-2222-2222-222222222222") + .acsEntranceIds(List.of( + "f74e4879-5991-4e2f-a368-888983dcfbfc" + )) + .requestedAccessMethods(List.of( + RequestedAccessMethod.builder() + .mode("mobile_key") + .build() + )) + .startsAt("2025-07-13T15:00:00.000Z") + .endsAt("2025-07-16T11:00:00.000Z") + .build() +); +``` +{% endtab %} +{% endtabs %} + +**Output:** + +```json +{ + "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "instant_key_url": "https://ik.seam.co/ABCXYZ", + "requested_access_methods": [ + { + "mode": "mobile_key", + "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"] + } + ], + ... +} +``` + +## Step 2: Share the Instant Key URL + +Deliver the `instant_key_url` to your user. Common delivery methods include: + +- **Text message (SMS)** — Send the URL directly to your user's phone. +- **Email** — Include the URL in a welcome or check-in email. +- **In-app link** — Embed the URL in your web or mobile app. +- **QR code** — Generate a QR code from the URL for physical signage. + +When your user taps the link on their phone, the Instant Key opens as an iOS App Clip or Android Instant App. They can unlock the door immediately — no app store download needed. + +{% hint style="info" %} +The Instant Key URL is also available on the access method itself as `instant_key_url`. Both the Access Grant and the access method return the same URL. +{% endhint %} + +## Next Steps + +- [Instant Keys](../../capability-guides/instant-keys/) — Deep dive into how Instant Keys work, site setup, and advanced delivery options. +- [Delivering Instant Keys](../../capability-guides/instant-keys/delivering-instant-keys.md) — Detailed guide for sharing Instant Keys with your users. +- [Using Mobile Keys](using-mobile-keys.md) — Build a native mobile app experience with the Seam mobile SDKs. +- [Delivering Access Methods](delivering-access-methods.md) — Learn how to deliver all access method types to your users. diff --git a/docs/guides/use-cases/granting-access/using-key-cards.md b/docs/guides/use-cases/granting-access/using-key-cards.md new file mode 100644 index 000000000..6ffe1211b --- /dev/null +++ b/docs/guides/use-cases/granting-access/using-key-cards.md @@ -0,0 +1,470 @@ +--- +description: >- + Learn how to create an Access Grant with a key card access method, then encode + or assign the card to your user. +--- + +# Using Key Cards + +Key cards are plastic cards that unlock doors when presented to a card reader. When you request a `card` access method in an Access Grant, Seam creates a card credential. Depending on your access control system, you either encode the credential onto a physical card using a card encoder or the system assigns the credential to a pre-registered card automatically. + +Key cards work with: + +- **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and other ACS platforms that support card-based credentials. Specify entrances with `acs_entrance_ids` or use `space_ids`. + +## Before You Begin + +To use key cards, you need: + +- A [Seam API key](https://console.seam.co) +- A connected ACS that supports card-based credentials +- A [user identity](../../capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities/) representing the person who will receive the card +- An entrance that supports card access (`can_unlock_with_card` is `true`) +- For encoding: a compatible card encoder connected to Seam (see [Working with Card Encoders and Scanners](../../low-level-apis/access-systems/working-with-card-encoders-and-scanners/)) + +## Step 1: Verify Entrance Support + +List the entrances for your ACS and confirm that `can_unlock_with_card` is `true`. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const entrances = await seam.acs.entrances.list({ + acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', +}) + +const cardEntrances = entrances.filter( + (e) => e.can_unlock_with_card +) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/acs/entrances/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +entrances = seam.acs.entrances.list( + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +card_entrances = [ + e for e in entrances if e.can_unlock_with_card +] +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +entrances = seam.acs.entrances.list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +card_entrances = entrances.select do |e| + e.can_unlock_with_card +end +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$entrances = $seam->acs->entrances->list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +$cardEntrances = array_filter( + $entrances, + fn($e) => $e->can_unlock_with_card +); +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var entrances = seam.Acs.Entrances.List( + acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +var cardEntrances = entrances + .Where(e => e.CanUnlockWithCard) + .ToList(); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var entrances = seam.acs().entrances().list( + AcsEntrancesListRequest.builder() + .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339") + .build() +); +``` +{% endtab %} +{% endtabs %} + +## Step 2: Create an Access Grant with a Key Card + +Create an [Access Grant](./) specifying `card` as the requested access method mode. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const accessGrant = await seam.accessGrants.create({ + user_identity_id: '22222222-2222-2222-2222-222222222222', + acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'], + requested_access_methods: [ + { mode: 'card' } + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + "requested_access_methods": [{ "mode": "card" }], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +access_grant = seam.access_grants.create( + user_identity_id="22222222-2222-2222-2222-222222222222", + acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods=[{"mode": "card"}], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z", +) +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +access_grant = seam.access_grants.create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [{ mode: "card" }], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$accessGrant = $seam->access_grants->create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [["mode" => "card"]], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var accessGrant = seam.AccessGrants.Create( + userIdentityId: "22222222-2222-2222-2222-222222222222", + acsEntranceIds: new List + { + "f74e4879-5991-4e2f-a368-888983dcfbfc" + }, + requestedAccessMethods: new List + { + new RequestedAccessMethod { Mode = "card" } + }, + startsAt: "2025-07-13T15:00:00.000Z", + endsAt: "2025-07-16T11:00:00.000Z" +); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var accessGrant = seam.accessGrants().create( + AccessGrantsCreateRequest.builder() + .userIdentityId("22222222-2222-2222-2222-222222222222") + .acsEntranceIds(List.of( + "f74e4879-5991-4e2f-a368-888983dcfbfc" + )) + .requestedAccessMethods(List.of( + RequestedAccessMethod.builder() + .mode("card") + .build() + )) + .startsAt("2025-07-13T15:00:00.000Z") + .endsAt("2025-07-16T11:00:00.000Z") + .build() +); +``` +{% endtab %} +{% endtabs %} + +## Step 3: Deliver the Key Card + +Retrieve the access method and check the `is_encoding_required` property to determine whether you need to encode the card or whether the system assigns it automatically. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const accessMethod = await seam.accessMethods.get({ + access_method_id: + accessGrant.requested_access_methods[0].created_access_method_ids[0], +}) + +console.log(accessMethod.is_encoding_required) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +access_method = seam.access_methods.get( + access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +print(access_method.is_encoding_required) +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +access_method = seam.access_methods.get( + access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +puts access_method.is_encoding_required +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$accessMethod = $seam->access_methods->get( + access_method_id: $accessGrant->requested_access_methods[0]->created_access_method_ids[0] +); + +echo $accessMethod->is_encoding_required; +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var accessMethod = seam.AccessMethods.Get( + accessMethodId: accessGrant.RequestedAccessMethods[0].CreatedAccessMethodIds[0] +); + +Console.WriteLine(accessMethod.IsEncodingRequired); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var accessMethod = seam.accessMethods().get( + AccessMethodsGetRequest.builder() + .accessMethodId( + accessGrant.getRequestedAccessMethods().get(0).getCreatedAccessMethodIds().get(0) + ) + .build() +); +``` +{% endtab %} +{% endtabs %} + +**Output:** + +```json +{ + "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "display_name": "Key Card", + "mode": "card", + "is_issued": false, + "is_encoding_required": true, + ... +} +``` + +*** + +### Encoding Cards + +If `is_encoding_required` is `true`, you must encode the credential onto a physical card using a card encoder before handing the card to your user. + +Use the Seam API to encode the card: + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const actionAttempt = await seam.accessMethods.encode({ + access_method_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', + acs_encoder_id: 'encoder-001', +}) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/encode' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "acs_encoder_id": "encoder-001" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +action_attempt = seam.access_methods.encode( + access_method_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890", + acs_encoder_id="encoder-001", +) +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +action_attempt = seam.access_methods.encode( + access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + acs_encoder_id: "encoder-001" +) +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$actionAttempt = $seam->access_methods->encode( + access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + acs_encoder_id: "encoder-001" +); +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var actionAttempt = seam.AccessMethods.Encode( + accessMethodId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + acsEncoderId: "encoder-001" +); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var actionAttempt = seam.accessMethods().encode( + AccessMethodsEncodeRequest.builder() + .accessMethodId("a1b2c3d4-e5f6-7890-abcd-ef1234567890") + .acsEncoderId("encoder-001") + .build() +); +``` +{% endtab %} +{% endtabs %} + +Once encoding is complete, the access method's `is_encoding_required` property changes to `false` and `is_issued` changes to `true`. Hand the encoded card to your user. + +For the complete card encoding workflow, including listing encoders and scanning cards, see [Working with Card Encoders and Scanners](../../low-level-apis/access-systems/working-with-card-encoders-and-scanners/). + +*** + +### Assigning Cards + +If `is_encoding_required` is `false`, the ACS assigns the credential to a card automatically — no physical encoding step is needed. This is common with systems that use pre-registered or cloud-managed cards. + +In this case, once `is_issued` is `true`, the card is ready. Hand the assigned card to your user. + +## Next Steps + +- [Working with Card Encoders and Scanners](../../low-level-apis/access-systems/working-with-card-encoders-and-scanners/) — Complete guide to encoding and scanning cards. +- [Delivering Access Methods](delivering-access-methods.md) — Learn how to deliver all access method types to your users. +- [Creating an Access Grant](creating-an-access-grant.md) — Learn more about specifying devices, entrances, and spaces. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. diff --git a/docs/guides/use-cases/granting-access/using-mobile-keys.md b/docs/guides/use-cases/granting-access/using-mobile-keys.md new file mode 100644 index 000000000..0634bdd48 --- /dev/null +++ b/docs/guides/use-cases/granting-access/using-mobile-keys.md @@ -0,0 +1,382 @@ +--- +description: >- + Learn how to create an Access Grant with a mobile key access method and + deliver it through your mobile app using the Seam mobile SDKs. +--- + +# Using Mobile Keys + +Mobile keys let your users unlock doors by tapping a button in your mobile app. When you request a `mobile_key` access method in an Access Grant, Seam issues a mobile credential that you deliver through your own app using the Seam mobile SDKs. Each mobile key also includes an [Instant Key](../../capability-guides/instant-keys/) URL for immediate access without an app download. + +Mobile keys work with: + +- **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and other ACS platforms that support BLE-based mobile credentials. Specify entrances with `acs_entrance_ids` or use `space_ids`. + +## Before You Begin + +To use mobile keys, you need: + +- A [Seam API key](https://console.seam.co) +- A connected ACS with BLE-capable lock hardware +- Mobile key licenses or subscriptions activated for your ACS (requirements vary by system — see your [system integration guide](https://docs.seam.co/latest/device-and-system-integration-guides#access-control-systems)) +- A [user identity](../../capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities.md) representing the person who will receive the mobile key +- An entrance that supports mobile keys (`can_unlock_with_mobile_key` is `true`) + +{% hint style="info" %} +If you plan to build a mobile app that delivers mobile keys, see [Mobile Access](../../capability-guides/mobile-access/) for the complete SDK integration guide. If you just want to share a link for instant access, see [Using Instant Keys](using-instant-keys.md) instead. +{% endhint %} + +## Step 1: Verify Entrance Support + +List the entrances for your ACS and confirm that `can_unlock_with_mobile_key` is `true`. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const entrances = await seam.acs.entrances.list({ + acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', +}) + +const mobileKeyEntrances = entrances.filter( + (e) => e.can_unlock_with_mobile_key +) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/acs/entrances/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +entrances = seam.acs.entrances.list( + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +mobile_key_entrances = [ + e for e in entrances if e.can_unlock_with_mobile_key +] +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +entrances = seam.acs.entrances.list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +mobile_key_entrances = entrances.select do |e| + e.can_unlock_with_mobile_key +end +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$entrances = $seam->acs->entrances->list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +$mobileKeyEntrances = array_filter( + $entrances, + fn($e) => $e->can_unlock_with_mobile_key +); +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var entrances = seam.Acs.Entrances.List( + acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +var mobileKeyEntrances = entrances + .Where(e => e.CanUnlockWithMobileKey) + .ToList(); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var entrances = seam.acs().entrances().list( + AcsEntrancesListRequest.builder() + .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339") + .build() +); +``` +{% endtab %} +{% endtabs %} + +## Step 2: Create an Access Grant with a Mobile Key + +Create an [Access Grant](./) specifying `mobile_key` as the requested access method mode. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const accessGrant = await seam.accessGrants.create({ + user_identity_id: '22222222-2222-2222-2222-222222222222', + acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'], + requested_access_methods: [ + { mode: 'mobile_key' } + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + "requested_access_methods": [{ "mode": "mobile_key" }], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +access_grant = seam.access_grants.create( + user_identity_id="22222222-2222-2222-2222-222222222222", + acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods=[{"mode": "mobile_key"}], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z", +) +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +access_grant = seam.access_grants.create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [{ mode: "mobile_key" }], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$accessGrant = $seam->access_grants->create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [["mode" => "mobile_key"]], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var accessGrant = seam.AccessGrants.Create( + userIdentityId: "22222222-2222-2222-2222-222222222222", + acsEntranceIds: new List + { + "f74e4879-5991-4e2f-a368-888983dcfbfc" + }, + requestedAccessMethods: new List + { + new RequestedAccessMethod { Mode = "mobile_key" } + }, + startsAt: "2025-07-13T15:00:00.000Z", + endsAt: "2025-07-16T11:00:00.000Z" +); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var accessGrant = seam.accessGrants().create( + AccessGrantsCreateRequest.builder() + .userIdentityId("22222222-2222-2222-2222-222222222222") + .acsEntranceIds(List.of( + "f74e4879-5991-4e2f-a368-888983dcfbfc" + )) + .requestedAccessMethods(List.of( + RequestedAccessMethod.builder() + .mode("mobile_key") + .build() + )) + .startsAt("2025-07-13T15:00:00.000Z") + .endsAt("2025-07-16T11:00:00.000Z") + .build() +); +``` +{% endtab %} +{% endtabs %} + +## Step 3: Deliver the Mobile Key + +Once the access method is issued, retrieve it to get the `client_session_id`. Use this value to initialize the Seam mobile SDK on your user's device so they can unlock doors from your app. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const accessMethod = await seam.accessMethods.get({ + access_method_id: + accessGrant.requested_access_methods[0].created_access_method_ids[0], +}) + +console.log(accessMethod.client_session_id) +console.log(accessMethod.instant_key_url) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +access_method = seam.access_methods.get( + access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +print(access_method.client_session_id) +print(access_method.instant_key_url) +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +access_method = seam.access_methods.get( + access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +puts access_method.client_session_id +puts access_method.instant_key_url +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$accessMethod = $seam->access_methods->get( + access_method_id: $accessGrant->requested_access_methods[0]->created_access_method_ids[0] +); + +echo $accessMethod->client_session_id; +echo $accessMethod->instant_key_url; +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var accessMethod = seam.AccessMethods.Get( + accessMethodId: accessGrant.RequestedAccessMethods[0].CreatedAccessMethodIds[0] +); + +Console.WriteLine(accessMethod.ClientSessionId); +Console.WriteLine(accessMethod.InstantKeyUrl); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var accessMethod = seam.accessMethods().get( + AccessMethodsGetRequest.builder() + .accessMethodId( + accessGrant.getRequestedAccessMethods().get(0).getCreatedAccessMethodIds().get(0) + ) + .build() +); +``` +{% endtab %} +{% endtabs %} + +**Output:** + +```json +{ + "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", + "display_name": "Mobile Key", + "mode": "mobile_key", + "is_issued": true, + "issued_at": "2025-06-16T16:55:03.924353Z", + "client_session_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... +} +``` + +Use the `client_session_id` to look up the client session token, then pass it to the Seam mobile SDK to initialize your user's mobile app. For the complete mobile SDK integration guide, see [Mobile Access](../../capability-guides/mobile-access/). + +{% hint style="info" %} +Every mobile key also includes an `instant_key_url`. You can share this URL with your user as an alternative or backup access method — no app download required. See [Using Instant Keys](using-instant-keys.md). +{% endhint %} + +## Next Steps + +- [Mobile Access](../../capability-guides/mobile-access/) — Complete guide to building a mobile app with the Seam mobile SDKs. +- [Using Instant Keys](using-instant-keys.md) — Share the Instant Key URL included with every mobile key. +- [Delivering Access Methods](delivering-access-methods.md) — Learn how to deliver all access method types to your users. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. diff --git a/docs/guides/use-cases/granting-access/using-pin-codes.md b/docs/guides/use-cases/granting-access/using-pin-codes.md new file mode 100644 index 000000000..e09ddd0be --- /dev/null +++ b/docs/guides/use-cases/granting-access/using-pin-codes.md @@ -0,0 +1,460 @@ +--- +description: >- + Learn how to create an Access Grant with a PIN code access method and deliver + the code to your user. +--- + +# Using PIN Codes + +PIN codes are the simplest access method. When you request a `code` access method in an Access Grant, Seam programs a PIN code onto the lock. Your user enters the code on the lock's keypad to unlock the door. + +PIN codes work with: + +- **Standalone smart locks** — August, Yale, Schlage, Lockly, TTLock, Tedee, igloohome, and other connected locks. Specify the locks with `device_ids`. +- **Access control systems** — Salto KS, Salto Space, Brivo, dormakaba, and other ACS platforms that support PIN-based credentials. Specify entrances with `acs_entrance_ids` or group access points into spaces and use `space_ids`. + +## Before You Begin + +To use PIN codes, you need: + +- A [Seam API key](https://console.seam.co) +- One or more connected devices or ACS entrances that support PIN codes +- For standalone smart locks: confirm that `can_program_online_access_codes` is `true` on the device +- For ACS entrances: confirm that `can_unlock_with_code` is `true` on the entrance + +## Step 1: Verify Device or Entrance Support + +### Standalone Smart Locks + +List your devices and confirm that `can_program_online_access_codes` is `true`. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const devices = await seam.devices.list() + +const pinCapableDevices = devices.filter( + (d) => d.can_program_online_access_codes +) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/devices/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +devices = seam.devices.list() + +pin_capable_devices = [ + d for d in devices if d.can_program_online_access_codes +] +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +devices = seam.devices.list + +pin_capable_devices = devices.select do |d| + d.can_program_online_access_codes +end +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$devices = $seam->devices->list(); + +$pinCapableDevices = array_filter( + $devices, + fn($d) => $d->can_program_online_access_codes +); +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var devices = seam.Devices.List(); + +var pinCapableDevices = devices + .Where(d => d.CanProgramOnlineAccessCodes) + .ToList(); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var devices = seam.devices().list( + DevicesListRequest.builder().build() +); +``` +{% endtab %} +{% endtabs %} + +### ACS Entrances + +List the entrances for your ACS and confirm that `can_unlock_with_code` is `true`. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const entrances = await seam.acs.entrances.list({ + acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', +}) + +const codeEntrances = entrances.filter( + (e) => e.can_unlock_with_code +) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/acs/entrances/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +entrances = seam.acs.entrances.list( + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +code_entrances = [ + e for e in entrances if e.can_unlock_with_code +] +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +entrances = seam.acs.entrances.list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +code_entrances = entrances.select do |e| + e.can_unlock_with_code +end +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$entrances = $seam->acs->entrances->list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +$codeEntrances = array_filter( + $entrances, + fn($e) => $e->can_unlock_with_code +); +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var entrances = seam.Acs.Entrances.List( + acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +var codeEntrances = entrances + .Where(e => e.CanUnlockWithCode) + .ToList(); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var entrances = seam.acs().entrances().list( + AcsEntrancesListRequest.builder() + .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339") + .build() +); +``` +{% endtab %} +{% endtabs %} + +## Step 2: Create an Access Grant with a PIN Code + +Create an [Access Grant](README.md) specifying `code` as the requested access method mode. You can target devices, entrances, or spaces. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const accessGrant = await seam.accessGrants.create({ + user_identity_id: '22222222-2222-2222-2222-222222222222', + device_ids: ['6ba7b811-9dad-11d1-80b4-00c04fd430c8'], + requested_access_methods: [ + { mode: 'code' } + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + "requested_access_methods": [{ "mode": "code" }], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +access_grant = seam.access_grants.create( + user_identity_id="22222222-2222-2222-2222-222222222222", + device_ids=["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods=[{"mode": "code"}], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z", +) +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +access_grant = seam.access_grants.create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods: [{ mode: "code" }], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$accessGrant = $seam->access_grants->create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods: [["mode" => "code"]], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var accessGrant = seam.AccessGrants.Create( + userIdentityId: "22222222-2222-2222-2222-222222222222", + deviceIds: new List + { + "6ba7b811-9dad-11d1-80b4-00c04fd430c8" + }, + requestedAccessMethods: new List + { + new RequestedAccessMethod { Mode = "code" } + }, + startsAt: "2025-07-13T15:00:00.000Z", + endsAt: "2025-07-16T11:00:00.000Z" +); +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var accessGrant = seam.accessGrants().create( + AccessGrantsCreateRequest.builder() + .userIdentityId("22222222-2222-2222-2222-222222222222") + .deviceIds(List.of( + "6ba7b811-9dad-11d1-80b4-00c04fd430c8" + )) + .requestedAccessMethods(List.of( + RequestedAccessMethod.builder() + .mode("code") + .build() + )) + .startsAt("2025-07-13T15:00:00.000Z") + .endsAt("2025-07-16T11:00:00.000Z") + .build() +); +``` +{% endtab %} +{% endtabs %} + +{% hint style="info" %} +In a sandbox workspace, PIN codes are issued almost instantly. On real devices, issuance can take a few moments. Poll the access method until `is_issued` is `true` or watch for the `access_method.issued` event. +{% endhint %} + +## Step 3: Retrieve the PIN Code + +Once the access method is issued, retrieve it to get the code. Share the code with your user through text, email, or your application. + +{% tabs %} +{% tab title="JavaScript" %} + + +```javascript +const accessMethod = await seam.accessMethods.get({ + access_method_id: + accessGrant.requested_access_methods[0].created_access_method_ids[0], +}) + +console.log(accessMethod.code) // => "1234" +``` +{% endtab %} + +{% tab title="cURL" %} + + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" +}' +``` +{% endtab %} + +{% tab title="Python" %} + + +```python +access_method = seam.access_methods.get( + access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +print(access_method.code) # => "1234" +``` +{% endtab %} + +{% tab title="Ruby" %} + + +```ruby +access_method = seam.access_methods.get( + access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +puts access_method.code # => "1234" +``` +{% endtab %} + +{% tab title="PHP" %} + + +```php +$accessMethod = $seam->access_methods->get( + access_method_id: $accessGrant->requested_access_methods[0]->created_access_method_ids[0] +); + +echo $accessMethod->code; // => "1234" +``` +{% endtab %} + +{% tab title="C#" %} + + +```csharp +var accessMethod = seam.AccessMethods.Get( + accessMethodId: accessGrant.RequestedAccessMethods[0].CreatedAccessMethodIds[0] +); + +Console.WriteLine(accessMethod.Code); // => "1234" +``` +{% endtab %} + +{% tab title="Java" %} + + +```java +var accessMethod = seam.accessMethods().get( + AccessMethodsGetRequest.builder() + .accessMethodId( + accessGrant.getRequestedAccessMethods().get(0).getCreatedAccessMethodIds().get(0) + ) + .build() +); +``` +{% endtab %} +{% endtabs %} + +**Output:** + +```json +{ + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name": "PIN Code", + "mode": "code", + "is_issued": true, + "issued_at": "2025-06-16T16:55:03.924353Z", + "code": "1234", + ... +} +``` + +## Next Steps + +- [Delivering Access Methods](delivering-access-methods.md) — Learn how to deliver all access method types to your users. +- [Creating an Access Grant](creating-an-access-grant.md) — Learn more about specifying devices, entrances, and spaces. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. diff --git a/mintlify-docs/SUMMARY.mdx b/mintlify-docs/SUMMARY.mdx index b32cbd4cf..22efce500 100644 --- a/mintlify-docs/SUMMARY.mdx +++ b/mintlify-docs/SUMMARY.mdx @@ -10,10 +10,13 @@ title: 'Table of contents' - [Granting Access](./use-cases/granting-access/index) - [Access Grant Quick Start](./use-cases/granting-access/access-grant-quick-start) - - [Creating an Access Grant Using Devices](./use-cases/granting-access/creating-an-access-grant-using-devices) - - [Creating an Access Grant Using Spaces](./use-cases/granting-access/creating-an-access-grant-using-spaces) - - [Creating an Access Grant Using Entrances](./use-cases/granting-access/creating-an-access-grant-using-entrances) + - [Creating an Access Grant](./use-cases/granting-access/creating-an-access-grant) - [Delivering Access Methods](./use-cases/granting-access/delivering-access-methods) + - [Using PIN Codes](./use-cases/granting-access/using-pin-codes) + - [Using Mobile Keys](./use-cases/granting-access/using-mobile-keys) + - [Using Instant Keys](./use-cases/granting-access/using-instant-keys) + - [Using Key Cards](./use-cases/granting-access/using-key-cards) + - [Using Cloud Keys](./use-cases/granting-access/using-cloud-keys) - [Reservation Access Grants](./use-cases/granting-access/reservation-access-grants) - [Retrieving Access Grants and Access Methods](./use-cases/granting-access/retrieving-access-grants-and-access-methods) - [Updating an Access Grant](./use-cases/granting-access/updating-an-access-grant) diff --git a/mintlify-docs/docs.json b/mintlify-docs/docs.json index c898d592e..d37103cd9 100644 --- a/mintlify-docs/docs.json +++ b/mintlify-docs/docs.json @@ -53,10 +53,12 @@ "pages": [ "use-cases/granting-access/index", "use-cases/granting-access/access-grant-quick-start", - "use-cases/granting-access/creating-an-access-grant-using-devices", - "use-cases/granting-access/creating-an-access-grant-using-spaces", - "use-cases/granting-access/creating-an-access-grant-using-entrances", + "use-cases/granting-access/creating-an-access-grant", "use-cases/granting-access/delivering-access-methods", + "use-cases/granting-access/using-pin-codes", + "use-cases/granting-access/using-mobile-keys", + "use-cases/granting-access/using-instant-keys", + "use-cases/granting-access/using-key-cards", "use-cases/granting-access/using-cloud-keys", "use-cases/granting-access/reservation-access-grants", "use-cases/granting-access/retrieving-access-grants-and-access-methods", @@ -3129,6 +3131,18 @@ { "source": "/yale-locks/yale-sample-data", "destination": "/device-and-system-integration-guides/yale-locks/yale-sample-data" + }, + { + "source": "/use-cases/granting-access/creating-an-access-grant-using-devices", + "destination": "/use-cases/granting-access/creating-an-access-grant" + }, + { + "source": "/use-cases/granting-access/creating-an-access-grant-using-spaces", + "destination": "/use-cases/granting-access/creating-an-access-grant" + }, + { + "source": "/use-cases/granting-access/creating-an-access-grant-using-entrances", + "destination": "/use-cases/granting-access/creating-an-access-grant" } ], "openapi": [ diff --git a/mintlify-docs/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods.mdx b/mintlify-docs/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods.mdx index 65478b0ad..28902b005 100644 --- a/mintlify-docs/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods.mdx +++ b/mintlify-docs/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods.mdx @@ -32,7 +32,7 @@ Once you have written an access method to a card, you cannot reuse the access me This example shows how to create a card access method as part of an Access Grant. Note that the `is_encoding_required` property of the resulting access method is `true`, which means that the access method must be encoded onto a card. Further, once you've encoded the access method on to the card, the `is_issued` property changes to `true`, and the `issued_at` property indicates the date and time at which the encoding occurred. -For more details about creating Access Grants, see [Creating an Access Grant Using Entrances](../../../use-cases/granting-access/creating-an-access-grant-using-entrances) and [Creating an Access Grant Using Spaces](../../../use-cases/granting-access/creating-an-access-grant-using-spaces). +For more details about creating Access Grants, see [Creating an Access Grant](../../../use-cases/granting-access/creating-an-access-grant). diff --git a/mintlify-docs/quickstart.mdx b/mintlify-docs/quickstart.mdx index 211945046..f2aa8e797 100644 --- a/mintlify-docs/quickstart.mdx +++ b/mintlify-docs/quickstart.mdx @@ -361,7 +361,7 @@ Here are some ideas of what you can do next... ### Go Deeper on Granting Access -You just created your first Access Grant. The same API issues mobile keys, [Instant Keys](./capability-guides/instant-keys/index), and plastic cards, grants access to multiple devices and [access system entrances](./use-cases/granting-access/creating-an-access-grant-using-entrances) in one call, and manages the full credential lifecycle. See the [Granting Access guide](./use-cases/granting-access/index). +You just created your first Access Grant. The same API issues mobile keys, [Instant Keys](./capability-guides/instant-keys/index), and plastic cards, grants access to multiple devices and [access system entrances](./use-cases/granting-access/creating-an-access-grant) in one call, and manages the full credential lifecycle. See the [Granting Access guide](./use-cases/granting-access/index). You can also control devices directly—for example, [lock and unlock doors](./low-level-apis/smart-locks/lock-and-unlock) remotely. diff --git a/mintlify-docs/use-cases/granting-access/access-grant-quick-start.mdx b/mintlify-docs/use-cases/granting-access/access-grant-quick-start.mdx index c7de044d2..ffa9a619f 100644 --- a/mintlify-docs/use-cases/granting-access/access-grant-quick-start.mdx +++ b/mintlify-docs/use-cases/granting-access/access-grant-quick-start.mdx @@ -9,7 +9,7 @@ In this quick start, create an Access Grant to give a user access to a set of ac **Starting with a standalone smart lock?** The fastest first success is a single device and a PIN code: see the [Seam Quick Start](../../quickstart), which creates an Access Grant on a sandbox August lock, or [Creating an Access - Grant Using Devices](/use-cases/granting-access/creating-an-access-grant-using-devices). This quick + Grant](/use-cases/granting-access/creating-an-access-grant#using-device-ids). This quick start walks through the more advanced access system (ACS) path, including key cards, mobile keys, and Instant Keys. @@ -792,8 +792,7 @@ The way in which you deliver an access method depends on the mode of access. The Now that you've created your first Access Grant, learn more about Access Grants. -- [Creating an Access Grant Using Entrances](/use-cases/granting-access/creating-an-access-grant-using-entrances) -- [Creating an Access Grant Using Spaces](/use-cases/granting-access/creating-an-access-grant-using-spaces) +- [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) - [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) - [Access Grants API Reference](https://docs.seam.co/latest/api/access_grants/) - [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-devices.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-devices.mdx deleted file mode 100644 index 6b3fc5d23..000000000 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-devices.mdx +++ /dev/null @@ -1,633 +0,0 @@ ---- -title: 'Creating an Access Grant Using Devices' -description: 'Learn how to create an Access Grant to give a user access to one or more devices, such as standalone smart locks.' ---- - -Granting access to a device is the simplest form of an Access Grant. You specify the user, one or more device IDs, the access schedule, and the desired access methods, and Seam takes care of creating and managing the underlying credentials on each device. - -This path works for standalone smart locks—such as August, Yale, Schlage, igloohome, and TTLock devices—that are connected to Seam through a [Connect Webview](/core-concepts/connect-webviews/index). The devices do not need to be part of an access control system. - -An Access Grant defines the following characteristics: - -- User identity: The user to whom you want to grant access. -- Devices: The set of devices to which you want to grant the user access. -- Access schedule: The starting and ending times for access. -- Access methods: The modes of access, such as PIN codes and mobile keys. - -This topic describes how to create an Access Grant using device IDs. To learn how to organize devices and entrances into spaces and grant access to a whole space, see [Creating an Access Grant Using Spaces](/use-cases/granting-access/creating-an-access-grant-using-spaces). To learn how to grant access to access system entrances, see [Creating an Access Grant Using Entrances](/use-cases/granting-access/creating-an-access-grant-using-entrances). - ---- - -## Access Grant Creation Process - -To create an Access Grant: - -1. [Identify the devices](#identify-devices) to which you want to grant the user access. -2. [Create a user identity](#create-a-user-identity) for the user to whom you want to grant access. Alternately, you can create a new user identity as part of the Access Grant creation action. -3. [Create an Access Grant](#create-an-access-grant) for the user identity to define the devices to which the user should have access, the starting and ending times for this access, and the requested access methods, such as `code`. - - The action returns the created Access Grant. - -4. [Retrieve the resulting access methods](#retrieve-the-access-methods) once they are issued. For a `code` access method, the returned access method includes the PIN code that you can deliver to your user. - ---- - -## Before You Begin - -To create an Access Grant for a device, first [connect](/core-concepts/connect-webviews/index) the device account to Seam. Then, confirm that the device supports access codes by checking its `can_program_online_access_codes` capability flag. - - - You can try this entire flow in a [sandbox - workspace](/core-concepts/workspaces/index#sandbox-workspaces) using sandbox - devices, such as the August sandbox locks. - - ---- - -## Identify Devices - -List your devices and identify the ones to which you want to grant the user access. Check the `can_program_online_access_codes` capability flag for each device. - -**Code:** - - - -```javascript JavaScript -const devices = await seam.devices.list() - -const lock = devices.find((device) => device.can_program_online_access_codes) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/devices/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -devices = seam.devices.list() - -lock = next( - device for device in devices - if device.can_program_online_access_codes -) -``` - -```ruby Ruby -devices = seam.devices.list - -lock = devices.find(&:can_program_online_access_codes) -``` - -```php PHP -$devices = $seam->devices->list(); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -[ - { - "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name": "Front Door", - "can_program_online_access_codes": true, - ... - }, - ... -] -``` - -```json cURL -{ - "devices": [ - { - "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name": "Front Door", - "can_program_online_access_codes": true, - ... - }, - ... - ] -} -``` - -```python Python -[ - Device( - device_id="6ba7b811-9dad-11d1-80b4-00c04fd430c8", - display_name="Front Door", - can_program_online_access_codes=true, - ... - ), - ... -] -``` - -```ruby Ruby -[ - { - "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name" => "Front Door", - "can_program_online_access_codes" => true, - ... - }, - ... -] -``` - -```php PHP -[ - [ - "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name" => "Front Door", - "can_program_online_access_codes" => true, - ... - ], - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Create a User Identity - -You can create a user identity before creating the Access Grant, you can retrieve an existing user identity, or you can skip this step and create a new user identity as part of the Access Grant creation action. - -To create a user identity, specify the unique `user_identity_key`, `email_address`, or `phone_number` of the user. - -**Code:** - - - -```javascript JavaScript -await seam.userIdentities.create({ - full_name: 'Jane Doe', - email_address: 'jane@example.com', -}) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/user_identities/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "full_name": "Jane Doe", - "email_address": "jane@example.com" -}' -``` - -```python Python -seam.user_identities.create( - full_name="Jane Doe", - email_address="jane@example.com" -) -``` - -```ruby Ruby -seam.user_identities.create( - full_name: "Jane Doe", - email_address: "jane@example.com", -) -``` - -```php PHP -$seam->user_identities->create( - full_name: "Jane Doe", - email_address: "jane@example.com" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... -} -``` - -```json cURL -{ - "user_identity": { - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... - } -} -``` - -```python Python -UserIdentity( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - full_name="Jane Doe", - email_address="jane@example.com", - ... -) -``` - -```ruby Ruby -{ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -} -``` - -```php PHP -[ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Create an Access Grant - -To create an Access Grant, specify the user identity, device IDs, starting and ending times, and requested access methods, such as `code`. - -To grant access to multiple devices at the same time, include all the desired device IDs in the `device_ids` array. Seam creates the requested access methods on each device. - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.create({ - user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - device_ids: ['6ba7b811-9dad-11d1-80b4-00c04fd430c8'], - requested_access_methods: [{ mode: 'code' }], - starts_at: '2025-07-13T15:00:00.000Z', - ends_at: '2025-07-16T11:00:00.000Z', -}) -``` - -```bash cURL -# Alternately, to create a new user identity, use the -# following parameter instead of user_identity_id: -# user_identity={ -# "full_name": "Jane Doe", -# "email_address": "jane.doe@example.com", -# }, -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "device_ids": [ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8" - ], - "requested_access_methods": [ - {"mode": "code"} - ], - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z" -}' -``` - -```python Python -seam.access_grants.create( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity={ - # "full_name": "Jane Doe", - # "email_address": "jane.doe@example.com", - # }, - device_ids=[ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8" - ], - requested_access_methods=[ - {"mode": "code"} - ], - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z" -) -``` - -```ruby Ruby -seam.access_grants.create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity: { - # full_name: "Jane Doe", - # email_address: "jane.doe@example.com", - # }, - device_ids: %w[6ba7b811-9dad-11d1-80b4-00c04fd430c8], - requested_access_methods: [ - {"mode": "code"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -) -``` - -```php PHP -$seam->access_grants->create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - device_ids: [ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - ], - requested_access_methods: [ - ["mode" => "code"], - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... -} -``` - -```json cURL -{ - "access_grant": { - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... - } -} -``` - -```python Python -AccessGrant( - access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - display_name="My Access Grant", - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z", - requested_access_methods=[ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... -) -``` - -```ruby Ruby -{ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "requested_access_methods" => [ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... -} -``` - -```php PHP -[ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "requested_access_methods" => [ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Retrieve the Access Methods - -Once an access method has been issued, retrieve it by ID. For a `code` access method, the returned access method includes the `code` that you can deliver to your user. - -You can poll the access method for the `is_issued` status change or watch for the `access_method.issued` event. - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.get({ - access_method_id: 'f47ac10b-58cc-4372-a567-0e02b2c3d479', -}) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" -}' -``` - -```python Python -seam.access_methods.get( - access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479" -) -``` - -```ruby Ruby -seam.access_methods.get( - access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" -) -``` - -```php PHP -$seam->access_methods->get( - access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name": "PIN Code", - "mode": "code", - "is_issued": true, - "code": "1234", - ... -} -``` - -```json cURL -{ - "access_method": { - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name": "PIN Code", - "mode": "code", - "is_issued": true, - "code": "1234", - ... - }, - "ok": true -} -``` - -```python Python -AccessMethod( - access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", - display_name="PIN Code", - mode="code", - is_issued=true, - code="1234", - ... -) -``` - -```ruby Ruby -{ - "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name" => "PIN Code", - "mode" => "code", - "is_issued" => true, - "code" => "1234", - ... -} -``` - -```php PHP -[ - "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name" => "PIN Code", - "mode" => "code", - "is_issued" => true, - "code" => "1234", - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Next Steps - -Once you've created the Access Grant and the resulting access methods have been issued, you can deliver the access methods to your user. For details, see [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods). - -To organize devices into logical groups—for example, all the locks that a guest staying in Unit 101 needs—and grant access to the whole group with a single ID, see [Creating an Access Grant Using Spaces](/use-cases/granting-access/creating-an-access-grant-using-spaces). diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-entrances.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-entrances.mdx deleted file mode 100644 index 5d63b821e..000000000 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-entrances.mdx +++ /dev/null @@ -1,783 +0,0 @@ ---- -title: 'Creating an Access Grant Using Entrances' -description: 'Learn how to create an access grant to define the "who, where, when, and how" for assigning a user access to entrances.' ---- - -An Access Grant defines the following characteristics: - -- User identity: The user to whom you want to grant access. -- Entrances: The set of entrances or other access points to which you want to grant the user access. -- Access schedule: The starting and ending times for access. -- Access methods: The modes of access, including key cards, PIN codes, mobile keys, and [Instant Keys](/capability-guides/instant-keys/index). - -It is important to note that you can specify the set of entrances to which you want to grant access using the IDs of the entrances themselves. Alternately, before creating an Access Grant, you can organize sets of entrances into spaces. Then, when you create an Access Grant, you specify the IDs of the spaces to which you want to grant access. Seam grants the user access to all entrances included in these spaces. - -This topic describes how to create an Access Grant using entrances. To learn how to create an Access Grant using spaces, see [Creating an Access Grant Using Spaces](/use-cases/granting-access/creating-an-access-grant-using-spaces). - ---- - -## Access Grant Creation Process - -To create an Access Grant: - -1. [Identify the entrances](#identify-entrances) to which you want to grant the user access. -2. [Create a user identity](#create-a-user-identity) for the user to whom you want to grant access. Alternately, you can create a new user identity as part of the Access Grant creation action. -3. [Create an Access Grant](#create-an-access-grant) for the user identity to define the entrances to which the user should have access, the starting and ending times for this access, and the requested access methods, that is, one or more of `card`, `code`, and `mobile_key`. - - The action returns the created Access Grant. - -4. [Monitor for lifecycle events](#monitor-for-lifecycle-events) to identify next steps, such as the following: - - Whether you need to encode a card access method onto a plastic card. - - When the access methods are ready to deliver to your user. - -If you've created an Access Grant that includes an mobile key, the returned Access Grant includes the Instant Key URL. to make it more efficient for you to share this URL with your user. - ---- - -## Before You Begin - -To create an Access Grant, first [connect](/core-concepts/workspaces/index#connecting-virtual-devices) an access system to Seam. You may also need to set up your access system and confirm that it has the required licenses. For details, see [Setting Up Your Site for Instant Keys](../../capability-guides/instant-keys/setting-up-your-site-for-instant-keys) and the [system integration guide](https://docs.seam.co/latest/device-and-system-integration-guides#access-control-systems) for your access system. - ---- - -## **Identify Entrances** - -List the entrances in the access system and identify the ones to which you want to grant the user access. - -**Code:** - - - -```javascript JavaScript -await seam.acs.entrances.list({ - acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', -}) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/acs/entrances/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" -}' -``` - -```python Python -seam.acs.entrances.list( - acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" -) -``` - -```ruby Ruby -seam.acs.entrances.list( - acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" -) -``` - -```php PHP -$seam->acs->entrances->list( - acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -[ - { - "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name": "Main Entrance", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - { - "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc", - "display_name": "Room 101", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - ... -] -``` - -```json cURL -{ - "acs_entrances": [ - { - "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name": "Main Entrance", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - { - "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc", - "display_name": "Room 101", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - ... - ] -} -``` - -```python Python -[ - AcsEntrance( - acs_entrance_id="48ebfb50-c531-43c5-b9ea-409f26dabbd7", - display_name="Main Entrance", - acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ), - AcsEntrance( - acs_entrance_id="f74e4879-5991-4e2f-a368-888983dcfbfc", - display_name="Room 101", - acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ), - ... -] -``` - -```json Ruby -[ - { - "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name" => "Main Entrance", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - { - "acs_entrance_id" => "f74e4879-5991-4e2f-a368-888983dcfbfc", - "display_name" => "Room 101", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - ... -] -``` - -```php PHP -[ - [ - "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name" => "Main Entrance", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ], - [ - "acs_entrance_id" => "f74e4879-5991-4e2f-a368-888983dcfbfc", - "display_name" => "Room 101", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ], - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -## **Create a User Identity** - -You can create a user identity before creating the Access Grant, you can retrieve an existing user identity, or you can skip this step and [create a new user identity as part of the Access Grant creation action](#create-an-access-grant). - -To create a user identity, specify the unique `user_identity_key`, `email_address`, or `phone_number` of the user. Also, include the ID of the access system in which you want to grant the user access. - -**Code:** - - - -```javascript JavaScript -await seam.userIdentities.create({ - full_name: 'Jane Doe', - email_address: 'jane@example.com', - acs_system_ids: ['c359cba2-8ef2-47fc-bee0-1c7c2a886339'], -}) -``` - -```curl cURL -curl -X 'POST' \ - 'https://connect.getseam.com/user_identities/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "full_name": "Jane Doe", - "email_address": "jane@example.com", - "acs_system_ids": [ - "c359cba2-8ef2-47fc-bee0-1c7c2a886339" - ] -}' -``` - -```python Python -seam.user_identities.create( - full_name="Jane Doe", - email_address="jane@example.com", - acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -) -``` - -```ruby Ruby -seam.user_identities.create( - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], -) -``` - -```php PHP -$seam->user_identities->create( - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... -} -``` - -```json cURL -{ - "user_identity": { - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... - } -} -``` - -```python Python -UserIdentity( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - full_name="Jane Doe", - email_address="jane@example.com", - ... -) -``` - -```ruby Ruby -{ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -} -``` - -```php PHP -[ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## **Create an Access Grant** - -To create an Access Grant, specify the user identity, entrance IDs, starting and ending times, and requested access methods, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, specify `mobile_key` as the mode for a requested access method. - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.create({ - user_identity_id: 'e3d736c1-540d-4d10-83e5-9a4e135453b4', - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - acs_entrance_ids: [ - '48ebfb50-c531-43c5-b9ea-409f26dabbd7', - 'f74e4879-5991-4e2f-a368-888983dcfbfc', - ], - requested_access_methods: [ - { mode: 'code' }, - { mode: 'card' }, - { mode: 'mobile_key' }, - ], - starts_at: '2025-07-13T15:00:00.000Z', - ends_at: '2025-07-16T11:00:00.000Z', -}) -``` - -```curl cURL -# Alternately, to create a new user identity, use the -# following parameter instead of user_identity_id: -# user_identity={ -# "full_name": "Jane Doe", -# "email_address": "jane.doe@example.com", -# }, -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "acs_entrance_ids": [ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc" - ], - "requested_access_methods": [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z" -}' -``` - -```python Python -seam.access_grants.create( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity={ - # "full_name": "Jane Doe", - # "email_address": "jane.doe@example.com", - # }, - acs_entrance_ids=[ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc" - ], - requested_access_methods=[ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z" -) -``` - -```ruby Ruby -seam.access_grants.create( - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity: { - # full_name: "Jane Doe", - # email_address: "jane.doe@example.com", - # }, - acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc], - requested_access_methods: [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -) -``` - -```php PHP -$seam->access_grants->create( - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - acs_entrance_ids: [ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc", - ], - requested_access_methods: [ - ["mode" => "code"], - ["mode" => "card"], - ["mode" => "mobile_key"], - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... -} -``` - -```json cURL -{ - "access_grant": { - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key Credential", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... - } -} -``` - -```python Python -AccessGrant( - access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - display_name="My Access Grant", - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z", - requested_access_methods=[ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - instant_key_url="https://ik.seam.co/ABCXYZ", - ... -) -``` - -```ruby Ruby -{ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "requested_access_methods" => [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -} -``` - -```php PHP -[ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "requested_access_methods" => [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Poll for Status Changes or Monitor for Lifecycle Events - -Once you've created an Access Grant with one or more access methods, poll the created access methods for status changes or watch for Access Grant and access method lifecycle events. The `access_method.is_issued` property and event let you know when an access method is ready to deliver to your user. - -### Poll for Status Changes - -To poll the created access methods, get these access methods by ID and look for the following status changes: - -- If `access_method.is_encoding_required` is `true`, you must encode the card access method onto a plastic key card. Once you've encoded the access method onto a card, this property changes to `false`. -- When an access method is ready to be delivered to a user, `access_method.is_issued` changes to `true`. For a card access method, `access_method.is_issued` changes to `true` after you encode the plastic card. You can also view the `access_method.issued_at` property to learn when the access method was issued. - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.get({ - access_method_id: 'c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f', -}) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -}' -``` - -```python Python -seam.access_methods.get( - access_method_id = "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -```ruby Ruby -seam.access_methods.get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -```php PHP -$seam->access_methods->get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... -} -``` - -```json cURL -{ - "access_method": { - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... - }, - "ok": true -} -``` - -```json Python -AccessMethod( - access_method_id="c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - display_name="Plastic Card", - mode="card", - created_at="2025-06-16T16:54:19.946606Z", - is_card_encoding_required=true, - is_issued=false, - issued_at=null, - ... -) -``` - -```json Ruby -{ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -} -``` - -```json PHP -[ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -### Monitor for Lifecycle Events - -Watch for the following Access Grant and access method events that include the IDs of the created Access Grant and access methods: - -- `access_grant.access_granted_to_door` -- `access_grant.access_granted_to_all_doors` -- `access_method.card_encoding_required` -- `access_method.issued` - -These events tell you what to do next. For example, if you've created a card access method, `access_method.card_encoding_required` lets you know that you need to encode the access method onto a plastic card. `access_grant.access_granted_to_all_doors` tells you that Seam has successfully created all the access methods that you requested through an Access Grant. `access_method.issued` indicates that you can now deliver the access method to your user. - -The following example shows the payload for an `access_method.card_encoding_required` event: - -```json -{ - "event_id": "22222222-3333-4444-5555-666666666666", - "event_description": "An access method representing a physical card requires encoding.", - "event_type": "access_method.card_encoding_required", - "acs_system_id": "11111111-1111-1111-1111-111111111111", - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - ... -} -``` - ---- - -## Next Steps - -Once you've created the Access Grant and the resulting access methods have been issued, you can deliver the access methods to your user. For details, see [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods). diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-spaces.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-spaces.mdx deleted file mode 100644 index f397d9c28..000000000 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant-using-spaces.mdx +++ /dev/null @@ -1,806 +0,0 @@ ---- -title: 'Creating an Access Grant Using Spaces' -description: 'Learn how to create an Access Grant to define the "who, where, when, and how" for assigning a user access to entrances grouped into spaces.' ---- - -An Access Grant defines the following characteristics: - -- User identity: The user to whom you want to grant access. -- Entrances or spaces: The sets of entrances or other access points to which you want to grant the user access. -- Access schedule: The starting and ending times for access. -- Access methods: The modes of access, including key cards, PIN codes, mobile keys, and [Instant Keys](/capability-guides/instant-keys/index). - -Before creating an Access Grant, you can organize sets of entrances into [spaces](https://docs.seam.co/latest/api/spaces/). Then, when you create an Access Grant, you specify the IDs of the spaces to which you want to grant access. Seam grants the user access to all entrances included in these spaces. Alternately, you can specify the set of entrances to which you want to grant access using the IDs of the entrances themselves. - -This topic describes how to create an Access Grant using spaces. To learn how to create an Access Grant using entrances, see [Creating an Access Grant Using Entrances](/use-cases/granting-access/creating-an-access-grant-using-entrances). - ---- - -## Access Grant Creation Process - -To create an Access Grant: - -1. [Identify the spaces](#identify-spaces) to which you want to grant the user access. -2. [Create a user identity](#create-a-user-identity) for the user to whom you want to grant access. Alternately, you can create a new user identity as part of the Access Grant creation action. -3. [Create an access grant](#create-an-access-grant) for the user identity to define the entrances to which the user should have access, the starting and ending times for this access, and the requested access methods, that is, one or more of `card`, `code`, and `mobile_key`. - - The action returns the created Access Grant. - -4. [Poll for status changes or monitor for lifecycle events](#poll-for-status-changes-or-monitor-for-lifecycle-events) to identify next steps, such as the following: - - Whether you need to encode a card access method onto a plastic card. - - When the access methods are ready to deliver to your user. - -If you've created an Access Grant that includes an mobile key, the returned Access Grant includes the Instant Key URL. to make it more efficient for you to share this URL with your user. - ---- - -## Before You Begin - -To create an Access Grant, first [connect](/core-concepts/workspaces/index#connecting-virtual-devices) an access system to Seam. You may also need to set up your access system and confirm that it has the required licenses. For details, see [Setting Up Your Site for Instant Keys](../../capability-guides/instant-keys/setting-up-your-site-for-instant-keys) and the [system integration guide](https://docs.seam.co/latest/device-and-system-integration-guides#access-control-systems) for your access system. - -Create one or more spaces to group the entrances to which you want to grant access. For details, see [Spaces](https://docs.seam.co/latest/api/spaces/) and [Create a Space](https://docs.seam.co/latest/api/spaces/create). - ---- - -## **Identify Spaces** - -List the spaces and identify the ones to which you want to grant the user access. - -**Code:** - - - -```javascript JavaScript -await seam.spaces.list() -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/spaces/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -seam.spaces.list() -``` - -```ruby Ruby -seam.spaces.list() -``` - -```php PHP -$seam->spaces->list(); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -[ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -] -``` - -```json cURL -{ - "spaces": [ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... - ], - ok: true -} -``` - -```python Python -[ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -] -``` - -```json Ruby -[ - { - "created_at" => "2025-06-16T16:54:17.946600Z", - "display_name" => "Room 101", - "name" => "Room 101", - "space_id" => "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at" => "2025-06-16T16:55:31.429200Z", - "display_name" => "Common Doors", - "name" => "Common Doors", - "space_id" => "550e8400-e29b-41d4-a716-446655440000", - "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -] -``` - -```php PHP -[ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -## **Create a User Identity** - -You can create a user identity before creating the Access Grant, you can retrieve an existing user identity, or you can skip this step and [create a new user identity as part of the Access Grant creation action](#create-an-access-grant). - -To create a user identity, specify the unique `user_identity_key`, `email_address`, or `phone_number` of the user. Also, include the ID of the access system in which you want to grant the user access. - -**Code:** - - - -```javascript JavaScript -await seam.userIdentities.create({ - full_name: 'Jane Doe', - email_address: 'jane@example.com', - acs_system_ids: ['c359cba2-8ef2-47fc-bee0-1c7c2a886339'], -}) -``` - -```curl cURL -curl -X 'POST' \ - 'https://connect.getseam.com/user_identities/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "full_name": "Jane Doe", - "email_address": "jane@example.com", - "acs_system_ids": [ - "c359cba2-8ef2-47fc-bee0-1c7c2a886339" - ] -}' -``` - -```python Python -seam.user_identities.create( - full_name="Jane Doe", - email_address="jane@example.com", - acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -) -``` - -```ruby Ruby -seam.user_identities.create( - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], -) -``` - -```php PHP -$seam->user_identities->create( - full_name: "Jane Doe", - email_address: "jane@example.com", - acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... -} -``` - -```json cURL -{ - "user_identity": { - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... - } -} -``` - -```python Python -UserIdentity( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - full_name="Jane Doe", - email_address="jane@example.com", - ... -) -``` - -```ruby Ruby -{ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -} -``` - -```php PHP -[ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## **Create an Access Grant** - -To create an Access Grant, specify the user identity, entrance IDs, starting and ending times, and requested access methods, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, specify `mobile_key` as the mode for a requested access method. - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.create({ - user_identity_id: 'e3d736c1-540d-4d10-83e5-9a4e135453b4', - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - space_ids: [ - '5afeb047-3277-4102-b8c4-99edf05b91d2', - '550e8400-e29b-41d4-a716-446655440000', - ], - requested_access_methods: [ - { mode: 'code' }, - { mode: 'card' }, - { mode: 'mobile_key' }, - ], - starts_at: '2025-07-13T15:00:00.000Z', - ends_at: '2025-07-16T11:00:00.000Z', -}) -``` - -```curl cURL -# Alternately, to create a new user identity, use the -# following parameter instead of user_identity_id: -# user_identity={ -# "full_name": "Jane Doe", -# "email_address": "jane.doe@example.com", -# }, -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "space_ids": [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods": [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z" -}' -``` - -```python Python -seam.access_grants.create( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity={ - # "full_name": "Jane Doe", - # "email_address": "jane.doe@example.com", - # }, - space_ids=[ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - requested_access_methods=[ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z" -) -``` - -```ruby Ruby -seam.access_grants.create( - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - # Alternately, to create a new user identity, use the - # following parameter instead of user_identity_id: - # user_identity: { - # full_name: "Jane Doe", - # email_address: "jane.doe@example.com", - # }, - space_ids: %w[5afeb047-3277-4102-b8c4-99edf05b91d2 550e8400-e29b-41d4-a716-446655440000], - requested_access_methods: [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -) -``` - -```php PHP -$seam->access_grants->create( - user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4", - // Alternately, to create a new user identity, use the - // following parameter instead of user_identity_id: - // user_identity: { - // full_name: "Jane Doe", - // email_address: "jane.doe@example.com", - // }, - space_ids: [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - requested_access_methods: [ - ["mode" => "code"], - ["mode" => "card"], - ["mode" => "mobile_key"], - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "space_ids": [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods": [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... -} -``` - -```json cURL -{ - "access_grant": { - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "space_ids": [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods": [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key Credential", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... - } -} -``` - -```python Python -AccessGrant( - access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - display_name="My Access Grant", - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z", - space_ids=[ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - requested_access_methods=[ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - instant_key_url="https://ik.seam.co/ABCXYZ", - ... -) -``` - -```ruby Ruby -{ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "space_ids" => [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods" => [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -} -``` - -```php PHP -[ - "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name" => "My Access Grant", - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at" => "2025-07-13T15:00:00.000Z", - "ends_at" => "2025-07-16T11:00:00.000Z", - "space_ids" => [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods" => [ - { - "display_name": "Plastic Card", - "mode": "card", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - ... - }, - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"], - ... - } - ], - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Poll for Status Changes or Monitor for Lifecycle Events - -Once you've created an Access Grant with one or more access methods, poll the created access methods for status changes or watch for Access Grant and access method lifecycle events. The `access_method.is_issued` property and event let you know when an access method is ready to deliver to your user. - -### Poll for Status Changes - -To poll the created access methods, get these access methods by ID and look for the following status changes: - -- If `access_method.is_encoding_required` is `true`, you must encode the card access method onto a plastic key card. Once you've encoded the access method onto a card, this property changes to `false`. -- When an access method is ready to be delivered to a user, `access_method.is_issued` changes to `true`. For a card access method, `access_method.is_issued` changes to `true` after you encode the plastic card. You can also view the `access_method.issued_at` property to learn when the access method was issued. - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.get({ - access_method_id: 'c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f', -}) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -}' -``` - -```python Python -seam.access_methods.get( - access_method_id = "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -```ruby Ruby -seam.access_methods.get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -```php PHP -$seam->access_methods->get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... -} -``` - -```json cURL -{ - "access_method": { - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... - }, - "ok": true -} -``` - -```json Python -AccessMethod( - access_method_id="c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - display_name="Plastic Card", - mode="card", - created_at="2025-06-16T16:54:19.946606Z", - is_card_encoding_required=true, - is_issued=false, - issued_at=null, - ... -) -``` - -```json Ruby -{ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -} -``` - -```json PHP -[ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -### Monitor for Lifecycle Events - -Watch for the following Access Grant and access method events that include the IDs of the created Access Grant and access methods: - -- `access_grant.access_granted_to_door` -- `access_grant.access_granted_to_all_doors` -- `access_method.card_encoding_required` -- `access_method.issued` - -These events tell you what to do next. For example, if you've created a card access method, `access_method.card_encoding_required` lets you know that you need to encode the access method onto a plastic card. `access_grant.access_granted_to_all_doors` tells you that Seam has successfully created all the access methods that you requested through an Access Grant. `access_method.issued` indicates that you can now deliver the access method to your user. - -The following example shows the payload for an `access_method.card_encoding_required` event: - -```json -{ - "event_id": "22222222-3333-4444-5555-666666666666", - "event_description": "An access method representing a physical card requires encoding.", - "event_type": "access_method.card_encoding_required", - "acs_system_id": "11111111-1111-1111-1111-111111111111", - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - ... -} -``` - ---- - -## Next Steps - -Once you've created the Access Grant and the resulting access methods have been issued, you can deliver the access methods to your user. For details, see [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods). diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx new file mode 100644 index 000000000..ff95d9c63 --- /dev/null +++ b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx @@ -0,0 +1,1435 @@ +--- +title: 'Creating an Access Grant' +description: 'Learn how to create an Access Grant to define the "who, where, when, and how" for assigning a user access to devices, spaces, or entrances.' +--- + +An Access Grant defines the following characteristics: + +- **User identity:** The user to whom you want to grant access. +- **Resources:** The set of devices, spaces, or entrances to which you want to grant the user access. +- **Access schedule:** The starting and ending times for access. +- **Access methods:** The modes of access, such as PIN codes, key cards, mobile keys, and [Instant Keys](/capability-guides/instant-keys/index). + +You specify which resources to grant access to using one of three parameters: + +| Parameter | Use case | Description | +| --- | --- | --- | +| `device_ids` | Standalone smart locks | Pass the IDs of individual devices, such as August, Yale, Schlage, igloohome, or TTLock locks connected through a [Connect Webview](/core-concepts/connect-webviews/index). | +| `space_ids` | Grouped access points | Organize entrances and devices into [spaces](https://docs.seam.co/latest/api/spaces/) first, then grant access to entire spaces. Useful for giving a guest access to everything they need (room door, main entrance, elevator) with one call. | +| `acs_entrance_ids` | Access control system entrances | Pass the IDs of individual ACS entrances. Use this when you want fine-grained control over which entrances to include. | + +You can also combine these parameters in a single Access Grant. + +--- + +## Access Grant Creation Process + +To create an Access Grant: + +1. [Identify your resources](#identify-your-resources)—the devices, spaces, or entrances to which you want to grant access. +2. [Create a user identity](#create-a-user-identity) for the user to whom you want to grant access. You can also create a new user identity as part of the Access Grant creation. +3. [Create an Access Grant](#create-an-access-grant) specifying the user identity, resources, access schedule, and requested access methods. +4. [Monitor for access method readiness](#monitor-for-access-method-readiness) to know when access methods are issued and ready to deliver. + +If you create an Access Grant that includes a mobile key, the returned Access Grant includes the Instant Key URL for efficient sharing. + +--- + +## Before You Begin + +**For standalone smart locks:** [Connect](/core-concepts/connect-webviews/index) the device account to Seam. Confirm that the device supports access codes by checking its `can_program_online_access_codes` capability flag. + + + You can try this entire flow in a [sandbox + workspace](/core-concepts/workspaces/index#sandbox-workspaces) using sandbox + devices, such as the August sandbox locks. + + +**For access control systems (spaces or entrances):** [Connect](/core-concepts/workspaces/index#connecting-virtual-devices) your access system to Seam. You may also need to set up your access system and confirm that it has the required licenses. For details, see [Setting Up Your Site for Instant Keys](../../capability-guides/instant-keys/setting-up-your-site-for-instant-keys) and the [system integration guide](https://docs.seam.co/latest/device-and-system-integration-guides#access-control-systems) for your access system. + +If you want to use spaces, create them first. For details, see [Spaces](https://docs.seam.co/latest/api/spaces/) and [Create a Space](https://docs.seam.co/latest/api/spaces/create). + +--- + +## Identify Your Resources + +Depending on your setup, identify the devices, spaces, or entrances to which you want to grant access. + +### List Devices + +List your devices and check the `can_program_online_access_codes` capability flag. + + + + +**Code:** + +```javascript +const devices = await seam.devices.list() + +const lock = devices.find((device) => device.can_program_online_access_codes) +``` + +**Output:** + +```json +[ + { + "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + "display_name": "Front Door", + "can_program_online_access_codes": true, + ... + }, + ... +] +``` + + + + + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/devices/list' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{}' +``` + +**Output:** + +```json +{ + "devices": [ + { + "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + "display_name": "Front Door", + "can_program_online_access_codes": true, + ... + }, + ... + ] +} +``` + + + + + +**Code:** + +```python +devices = seam.devices.list() + +lock = next( + device for device in devices + if device.can_program_online_access_codes +) +``` + +**Output:** + +```python +[ + Device( + device_id="6ba7b811-9dad-11d1-80b4-00c04fd430c8", + display_name="Front Door", + can_program_online_access_codes=true, + ... + ), + ... +] +``` + + + + + +**Code:** + +```ruby +devices = seam.devices.list + +lock = devices.find(&:can_program_online_access_codes) +``` + +**Output:** + +```ruby +[ + { + "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + "display_name" => "Front Door", + "can_program_online_access_codes" => true, + ... + }, + ... +] +``` + + + + + +**Code:** + +```php +$devices = $seam->devices->list(); +``` + +**Output:** + +```php +[ + [ + "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + "display_name" => "Front Door", + "can_program_online_access_codes" => true, + ... + ], + ... +]; +``` + + + + + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + + + + +### List Spaces + +List the spaces and identify the ones to which you want to grant access. + + + + +**Code:** + +```javascript +await seam.spaces.list() +``` + +**Output:** + +```json +[ + { + "created_at": "2025-06-16T16:54:17.946600Z", + "display_name": "Room 101", + "name": "Room 101", + "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + { + "created_at": "2025-06-16T16:55:31.429200Z", + "display_name": "Common Doors", + "name": "Common Doors", + "space_id": "550e8400-e29b-41d4-a716-446655440000", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + ... +] +``` + + + + + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/spaces/list' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{}' +``` + +**Output:** + +```json +{ + "spaces": [ + { + "created_at": "2025-06-16T16:54:17.946600Z", + "display_name": "Room 101", + "name": "Room 101", + "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + { + "created_at": "2025-06-16T16:55:31.429200Z", + "display_name": "Common Doors", + "name": "Common Doors", + "space_id": "550e8400-e29b-41d4-a716-446655440000", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + ... + ], + "ok": true +} +``` + + + + + +**Code:** + +```python +seam.spaces.list() +``` + +**Output:** + +```python +[ + { + "created_at": "2025-06-16T16:54:17.946600Z", + "display_name": "Room 101", + "name": "Room 101", + "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + ... +] +``` + + + + + +**Code:** + +```ruby +seam.spaces.list() +``` + +**Output:** + +```json +[ + { + "created_at" => "2025-06-16T16:54:17.946600Z", + "display_name" => "Room 101", + "name" => "Room 101", + "space_id" => "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" + }, + ... +] +``` + + + + + +**Code:** + +```php +$seam->spaces->list(); +``` + +**Output:** + +```php +[ + [ + "created_at" => "2025-06-16T16:54:17.946600Z", + "display_name" => "Room 101", + "name" => "Room 101", + "space_id" => "5afeb047-3277-4102-b8c4-99edf05b91d2", + "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" + ], + ... +]; +``` + + + + + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + + + + +### List Entrances + +List the entrances in your access system and identify the ones to which you want to grant access. + + + + +**Code:** + +```javascript +await seam.acs.entrances.list({ + acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', +}) +``` + +**Output:** + +```json +[ + { + "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "display_name": "Main Entrance", + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + }, + { + "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc", + "display_name": "Room 101", + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + }, + ... +] +``` + + + + + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/acs/entrances/list' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +}' +``` + +**Output:** + +```json +{ + "acs_entrances": [ + { + "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "display_name": "Main Entrance", + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + }, + ... + ] +} +``` + + + + + +**Code:** + +```python +seam.acs.entrances.list( + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) +``` + +**Output:** + +```python +[ + AcsEntrance( + acs_entrance_id="48ebfb50-c531-43c5-b9ea-409f26dabbd7", + display_name="Main Entrance", + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + ), + ... +] +``` + + + + + +**Code:** + +```ruby +seam.acs.entrances.list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) +``` + +**Output:** + +```json +[ + { + "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "display_name" => "Main Entrance", + "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + }, + ... +] +``` + + + + + +**Code:** + +```php +$seam->acs->entrances->list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); +``` + +**Output:** + +```php +[ + [ + "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "display_name" => "Main Entrance", + "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", + ... + ], + ... +]; +``` + + + + + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + + + + +--- + +## Create a User Identity + +You can create a user identity before creating the Access Grant, retrieve an existing one, or create a new user identity as part of the Access Grant creation action. + +To create a user identity, specify the unique `user_identity_key`, `email_address`, or `phone_number` of the user. If you are granting access to an access control system, also include the `acs_system_ids`. + + + + +**Code:** + +```javascript +await seam.userIdentities.create({ + full_name: 'Jane Doe', + email_address: 'jane@example.com', + // Include acs_system_ids if granting access to an ACS: + // acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], +}) +``` + +**Output:** + +```json +{ + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "full_name": "Jane Doe", + "email_address": "jane@example.com", + ... +} +``` + + + + + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/user_identities/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "full_name": "Jane Doe", + "email_address": "jane@example.com" +}' +``` + +**Output:** + +```json +{ + "user_identity": { + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "full_name": "Jane Doe", + "email_address": "jane@example.com", + ... + } +} +``` + + + + + +**Code:** + +```python +seam.user_identities.create( + full_name="Jane Doe", + email_address="jane@example.com" + # Include acs_system_ids if granting access to an ACS: + # acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] +) +``` + +**Output:** + +```python +UserIdentity( + user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", + full_name="Jane Doe", + email_address="jane@example.com", + ... +) +``` + + + + + +**Code:** + +```ruby +seam.user_identities.create( + full_name: "Jane Doe", + email_address: "jane@example.com", + # Include acs_system_ids if granting access to an ACS: + # acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], +) +``` + +**Output:** + +```ruby +{ + "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", + "full_name" => "Jane Doe", + "email_address" => "jane@example.com", + ... +} +``` + + + + + +**Code:** + +```php +$seam->user_identities->create( + full_name: "Jane Doe", + email_address: "jane@example.com" + // Include acs_system_ids if granting access to an ACS: + // acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] +); +``` + +**Output:** + +```php +[ + "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", + "full_name" => "Jane Doe", + "email_address" => "jane@example.com", + ... +]; +``` + + + + + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + + + + +--- + +## Create an Access Grant + +Specify the user identity, resources, access schedule, and requested access methods. The examples below show each resource type. + + + You can also create a new user identity inline by passing `user_identity` (with + `full_name` and `email_address`) instead of `user_identity_id`. + + +### Using Device IDs + +Use `device_ids` for standalone smart locks. To grant access to multiple devices, include all the desired device IDs in the array. + + + + +**Code:** + +```javascript +await seam.accessGrants.create({ + user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', + device_ids: ['6ba7b811-9dad-11d1-80b4-00c04fd430c8'], + requested_access_methods: [{ mode: 'code' }], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` + +**Output:** + +```json +{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "display_name": "My Access Grant", + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z", + "requested_access_methods": [ + { + "display_name": "PIN Code", + "mode": "code", + "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], + ... + } + ], + ... +} +``` + + + + + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "device_ids": [ + "6ba7b811-9dad-11d1-80b4-00c04fd430c8" + ], + "requested_access_methods": [ + {"mode": "code"} + ], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + +**Output:** + +```json +{ + "access_grant": { + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ... + } +} +``` + + + + + +**Code:** + +```python +seam.access_grants.create( + user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", + device_ids=[ + "6ba7b811-9dad-11d1-80b4-00c04fd430c8" + ], + requested_access_methods=[ + {"mode": "code"} + ], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z" +) +``` + + + + + +**Code:** + +```ruby +seam.access_grants.create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + device_ids: %w[6ba7b811-9dad-11d1-80b4-00c04fd430c8], + requested_access_methods: [ + {"mode": "code"} + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` + + + + + +**Code:** + +```php +$seam->access_grants->create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + device_ids: [ + "6ba7b811-9dad-11d1-80b4-00c04fd430c8", + ], + requested_access_methods: [ + ["mode" => "code"], + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` + + + + + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + + + + +### Using Space IDs + +Use `space_ids` to grant access to all entrances in one or more spaces. You can request multiple access method modes, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, include `mobile_key`. + + + + +**Code:** + +```javascript +await seam.accessGrants.create({ + user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', + space_ids: [ + '5afeb047-3277-4102-b8c4-99edf05b91d2', + '550e8400-e29b-41d4-a716-446655440000', + ], + requested_access_methods: [ + { mode: 'code' }, + { mode: 'card' }, + { mode: 'mobile_key' }, + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` + +**Output:** + +```json +{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "display_name": "My Access Grant", + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z", + "space_ids": [ + "5afeb047-3277-4102-b8c4-99edf05b91d2", + "550e8400-e29b-41d4-a716-446655440000" + ], + "requested_access_methods": [ + { + "display_name": "PIN Code", + "mode": "code", + ... + }, + { + "display_name": "Plastic Card", + "mode": "card", + ... + }, + { + "display_name": "Mobile Key", + "mode": "mobile_key", + ... + } + ], + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... +} +``` + + + + + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "space_ids": [ + "5afeb047-3277-4102-b8c4-99edf05b91d2", + "550e8400-e29b-41d4-a716-446655440000" + ], + "requested_access_methods": [ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + +**Output:** + +```json +{ + "access_grant": { + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ... + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... + } +} +``` + + + + + +**Code:** + +```python +seam.access_grants.create( + user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", + space_ids=[ + "5afeb047-3277-4102-b8c4-99edf05b91d2", + "550e8400-e29b-41d4-a716-446655440000" + ], + requested_access_methods=[ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z" +) +``` + + + + + +**Code:** + +```ruby +seam.access_grants.create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + space_ids: %w[5afeb047-3277-4102-b8c4-99edf05b91d2 550e8400-e29b-41d4-a716-446655440000], + requested_access_methods: [ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` + + + + + +**Code:** + +```php +$seam->access_grants->create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + space_ids: [ + "5afeb047-3277-4102-b8c4-99edf05b91d2", + "550e8400-e29b-41d4-a716-446655440000" + ], + requested_access_methods: [ + ["mode" => "code"], + ["mode" => "card"], + ["mode" => "mobile_key"], + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` + + + + + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + + + + +### Using Entrance IDs + +Use `acs_entrance_ids` to grant access to specific ACS entrances. You can request multiple access method modes, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, include `mobile_key`. + + + + +**Code:** + +```javascript +await seam.accessGrants.create({ + user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', + acs_entrance_ids: [ + '48ebfb50-c531-43c5-b9ea-409f26dabbd7', + 'f74e4879-5991-4e2f-a368-888983dcfbfc', + ], + requested_access_methods: [ + { mode: 'code' }, + { mode: 'card' }, + { mode: 'mobile_key' }, + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` + +**Output:** + +```json +{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "display_name": "My Access Grant", + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z", + "requested_access_methods": [ + { + "display_name": "PIN Code", + "mode": "code", + ... + }, + { + "display_name": "Plastic Card", + "mode": "card", + ... + }, + { + "display_name": "Mobile Key", + "mode": "mobile_key", + ... + } + ], + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... +} +``` + + + + + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", + "acs_entrance_ids": [ + "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "f74e4879-5991-4e2f-a368-888983dcfbfc" + ], + "requested_access_methods": [ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + +**Output:** + +```json +{ + "access_grant": { + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ... + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... + } +} +``` + + + + + +**Code:** + +```python +seam.access_grants.create( + user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", + acs_entrance_ids=[ + "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "f74e4879-5991-4e2f-a368-888983dcfbfc" + ], + requested_access_methods=[ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z" +) +``` + + + + + +**Code:** + +```ruby +seam.access_grants.create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc], + requested_access_methods: [ + {"mode": "code"}, + {"mode": "card"}, + {"mode": "mobile_key"} + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` + + + + + +**Code:** + +```php +$seam->access_grants->create( + user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", + acs_entrance_ids: [ + "48ebfb50-c531-43c5-b9ea-409f26dabbd7", + "f74e4879-5991-4e2f-a368-888983dcfbfc", + ], + requested_access_methods: [ + ["mode" => "code"], + ["mode" => "card"], + ["mode" => "mobile_key"], + ], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` + + + + + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + + + + +--- + +## Monitor for Access Method Readiness + +Once you've created an Access Grant, monitor the resulting access methods to know when they are ready to deliver to your user. + +### Poll for Status Changes + +Get the access methods by ID and check the following properties: + +- `is_encoding_required`: If `true`, you must encode the card access method onto a plastic key card. See [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index). +- `is_issued`: When `true`, the access method is ready to be delivered to your user. + + + + +**Code:** + +```javascript +await seam.accessMethods.get({ + access_method_id: 'f47ac10b-58cc-4372-a567-0e02b2c3d479', +}) +``` + +**Output:** + +```json +{ + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name": "PIN Code", + "mode": "code", + "is_issued": true, + "code": "1234", + ... +} +``` + + + + + +**Code:** + +```bash +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" +}' +``` + +**Output:** + +```json +{ + "access_method": { + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name": "PIN Code", + "mode": "code", + "is_issued": true, + "code": "1234", + ... + }, + "ok": true +} +``` + + + + + +**Code:** + +```python +seam.access_methods.get( + access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479" +) +``` + +**Output:** + +```python +AccessMethod( + access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", + display_name="PIN Code", + mode="code", + is_issued=true, + code="1234", + ... +) +``` + + + + + +**Code:** + +```ruby +seam.access_methods.get( + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" +) +``` + +**Output:** + +```ruby +{ + "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name" => "PIN Code", + "mode" => "code", + "is_issued" => true, + "code" => "1234", + ... +} +``` + + + + + +**Code:** + +```php +$seam->access_methods->get( + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" +); +``` + +**Output:** + +```php +[ + "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name" => "PIN Code", + "mode" => "code", + "is_issued" => true, + "code" => "1234", + ... +]; +``` + + + + + +**Code:** + +```csharp +// Coming Soon! +``` + +**Output:** + +```json +// Coming Soon! +``` + + + + +### Watch for Lifecycle Events + +You can also watch for the following Access Grant and access method events: + +- `access_grant.access_granted_to_door` — Seam has granted access to a specific door. +- `access_grant.access_granted_to_all_doors` — Seam has granted access to all requested doors. +- `access_method.card_encoding_required` — A card access method needs to be encoded onto a plastic card. +- `access_method.issued` — An access method is ready to deliver to your user. + +Example `access_method.card_encoding_required` event payload: + +```json +{ + "event_id": "22222222-3333-4444-5555-666666666666", + "event_description": "An access method representing a physical card requires encoding.", + "event_type": "access_method.card_encoding_required", + "acs_system_id": "11111111-1111-1111-1111-111111111111", + "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", + ... +} +``` + +--- + +## Next Steps + +Once you've created the Access Grant and the resulting access methods have been issued, deliver the access methods to your user. For details, see [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods). diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index ae6d062dc..449961f7c 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -107,9 +107,9 @@ Access Grants work across the entire Seam provider lineup: We recommend learning Access Grants in three steps, from the simplest setup to the most advanced: -1. **One device.** Connect a smart lock and create an Access Grant with a single `device_id` and a `code` access method. See [Creating an Access Grant Using Devices](/use-cases/granting-access/creating-an-access-grant-using-devices). -2. **Multiple devices and spaces.** Pass several `device_ids` in one call to grant access to a set of locks at once. To manage groups of access points by name—for example, everything a guest in Unit 101 needs—organize them into [spaces](/use-cases/granting-access/creating-an-access-grant-using-spaces) and grant access by `space_id`. -3. **Access control systems.** Connect an ACS, such as Salto, Visionline, or Brivo, and grant access to entrances with `acs_entrance_ids`. This path can involve additional setup, such as licenses, on-premises connections through Seam Bridge, mobile key configuration, and [reservations](/use-cases/granting-access/reservation-access-grants) for offline-override systems. See [Creating an Access Grant Using Entrances](/use-cases/granting-access/creating-an-access-grant-using-entrances). +1. **One device.** Connect a smart lock and create an Access Grant with a single `device_id` and a `code` access method. See [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant#using-device-ids). +2. **Multiple devices and spaces.** Pass several `device_ids` in one call to grant access to a set of locks at once. To manage groups of access points by name—for example, everything a guest in Unit 101 needs—organize them into [spaces](/use-cases/granting-access/creating-an-access-grant#using-space-ids) and grant access by `space_id`. +3. **Access control systems.** Connect an ACS, such as Salto, Visionline, or Brivo, and grant access to entrances with `acs_entrance_ids`. This path can involve additional setup, such as licenses, on-premises connections through Seam Bridge, mobile key configuration, and [reservations](/use-cases/granting-access/reservation-access-grants) for offline-override systems. See [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant#using-entrance-ids). --- @@ -291,16 +291,8 @@ The Access Grant process consists of the following steps: request.
See{' '} - - Creating an Access Grant Using Devices - - ,{' '} - - Creating an Access Grant Using Spaces - - , and{' '} - - Creating an Access Grant Using Entrances + + Creating an Access Grant .
You can poll for access method status changes or watch for Access Grant @@ -393,9 +385,7 @@ When issuing Access Grants for these systems, you’ll need to use reservations To create your first Access Grant, see the [Access Grant Quick Start](/use-cases/granting-access/access-grant-quick-start). Then, learn more in the following topics: -- [Creating an Access Grant Using Devices](/use-cases/granting-access/creating-an-access-grant-using-devices) -- [Creating an Access Grant Using Spaces](/use-cases/granting-access/creating-an-access-grant-using-spaces) -- [Creating an Access Grant Using Entrances](/use-cases/granting-access/creating-an-access-grant-using-entrances) +- [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) - [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) - [Access Grants API Reference](https://docs.seam.co/latest/api/access_grants/) - [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) diff --git a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx new file mode 100644 index 000000000..d3b36d46b --- /dev/null +++ b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx @@ -0,0 +1,185 @@ +--- +title: 'Using Instant Keys' +description: >- + Learn how to deliver Instant Keys — shareable unlock links that work without + an app download — through Access Grants. +--- + +Instant Keys are the fastest way to give someone mobile access. When you create an Access Grant with a `mobile_key` access method, Seam automatically generates an Instant Key URL. Share this URL with your user through text, email, or your app. When they tap the link, they can unlock the door immediately — no app download required. + +Instant Keys use iOS App Clips and Android Instant Apps to provide a native unlock experience without requiring your user to install anything. + +Instant Keys are ideal for: + +- **Guest access** — Send a link to a short-term guest (hotel, vacation rental, coworking space). +- **Backup access** — Provide a fallback unlock method alongside a native mobile key in your app. +- **Quick onboarding** — Let users unlock immediately while they set up your full mobile app. + +## Before You Begin + +To use Instant Keys, you need: + +- A [Seam API key](https://console.seam.co) +- A connected ACS with BLE-capable lock hardware that supports mobile keys +- Mobile key licenses activated for your ACS (see [Setting Up Your Site for Instant Keys](/capability-guides/instant-keys/setting-up-your-site-for-instant-keys)) +- A [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities) representing the person who will receive the Instant Key +- An entrance that supports mobile keys (`can_unlock_with_mobile_key` is `true`) + + + Instant Keys are generated automatically when you create a mobile key access + method. You do not need to request them separately. + + +## Step 1: Create an Access Grant with a Mobile Key + +Create an [Access Grant](/use-cases/granting-access/index) specifying `mobile_key` as the requested access method mode. The response includes an `instant_key_url` on the Access Grant itself — you can share it immediately without waiting for the access method to be issued. + + + +```javascript JavaScript +const accessGrant = await seam.accessGrants.create({ + user_identity_id: '22222222-2222-2222-2222-222222222222', + acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'], + requested_access_methods: [ + { mode: 'mobile_key' } + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) + +console.log(accessGrant.instant_key_url) +// => "https://ik.seam.co/ABCXYZ" +``` + +```python Python +access_grant = seam.access_grants.create( + user_identity_id="22222222-2222-2222-2222-222222222222", + acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods=[{"mode": "mobile_key"}], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z", +) + +print(access_grant.instant_key_url) +# => "https://ik.seam.co/ABCXYZ" +``` + +```ruby Ruby +access_grant = seam.access_grants.create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [{ mode: "mobile_key" }], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) + +puts access_grant.instant_key_url +# => "https://ik.seam.co/ABCXYZ" +``` + +```php PHP +$accessGrant = $seam->access_grants->create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [["mode" => "mobile_key"]], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); + +echo $accessGrant->instant_key_url; +// => "https://ik.seam.co/ABCXYZ" +``` + +```csharp C# +var accessGrant = seam.AccessGrants.Create( + userIdentityId: "22222222-2222-2222-2222-222222222222", + acsEntranceIds: new List + { + "f74e4879-5991-4e2f-a368-888983dcfbfc" + }, + requestedAccessMethods: new List + { + new RequestedAccessMethod { Mode = "mobile_key" } + }, + startsAt: "2025-07-13T15:00:00.000Z", + endsAt: "2025-07-16T11:00:00.000Z" +); + +Console.WriteLine(accessGrant.InstantKeyUrl); +// => "https://ik.seam.co/ABCXYZ" +``` + +```java Java +var accessGrant = seam.accessGrants().create( + AccessGrantsCreateRequest.builder() + .userIdentityId("22222222-2222-2222-2222-222222222222") + .acsEntranceIds(List.of( + "f74e4879-5991-4e2f-a368-888983dcfbfc" + )) + .requestedAccessMethods(List.of( + RequestedAccessMethod.builder() + .mode("mobile_key") + .build() + )) + .startsAt("2025-07-13T15:00:00.000Z") + .endsAt("2025-07-16T11:00:00.000Z") + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + "requested_access_methods": [{ "mode": "mobile_key" }], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + + + +**Output:** + +```json +{ + "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "instant_key_url": "https://ik.seam.co/ABCXYZ", + "requested_access_methods": [ + { + "mode": "mobile_key", + "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"] + } + ], + ... +} +``` + +## Step 2: Share the Instant Key URL + +Deliver the `instant_key_url` to your user. Common delivery methods include: + +- **Text message (SMS)** — Send the URL directly to your user's phone. +- **Email** — Include the URL in a welcome or check-in email. +- **In-app link** — Embed the URL in your web or mobile app. +- **QR code** — Generate a QR code from the URL for physical signage. + +When your user taps the link on their phone, the Instant Key opens as an iOS App Clip or Android Instant App. They can unlock the door immediately — no app store download needed. + + + The Instant Key URL is also available on the access method itself as + `instant_key_url`. Both the Access Grant and the access method return the + same URL. + + +## Next Steps + +- [Instant Keys](/capability-guides/instant-keys/index) — Deep dive into how Instant Keys work, site setup, and advanced delivery options. +- [Delivering Instant Keys](/capability-guides/instant-keys/delivering-instant-keys) — Detailed guide for sharing Instant Keys with your users. +- [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) — Build a native mobile app experience with the Seam mobile SDKs. +- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) — Learn how to deliver all access method types to your users. diff --git a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx new file mode 100644 index 000000000..eb4817dd6 --- /dev/null +++ b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx @@ -0,0 +1,365 @@ +--- +title: 'Using Key Cards' +description: >- + Learn how to create an Access Grant with a key card access method, then encode + or assign the card to your user. +--- + +Key cards are plastic cards that unlock doors when presented to a card reader. When you request a `card` access method in an Access Grant, Seam creates a card credential. Depending on your access control system, you either encode the credential onto a physical card using a card encoder or the system assigns the credential to a pre-registered card automatically. + +Key cards work with: + +- **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and other ACS platforms that support card-based credentials. Specify entrances with `acs_entrance_ids` or use `space_ids`. + +## Before You Begin + +To use key cards, you need: + +- A [Seam API key](https://console.seam.co) +- A connected ACS that supports card-based credentials +- A [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities) representing the person who will receive the card +- An entrance that supports card access (`can_unlock_with_card` is `true`) +- For encoding: a compatible card encoder connected to Seam (see [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index)) + +## Step 1: Verify Entrance Support + +List the entrances for your ACS and confirm that `can_unlock_with_card` is `true`. + + + +```javascript JavaScript +const entrances = await seam.acs.entrances.list({ + acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', +}) + +const cardEntrances = entrances.filter( + (e) => e.can_unlock_with_card +) +``` + +```python Python +entrances = seam.acs.entrances.list( + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +card_entrances = [ + e for e in entrances if e.can_unlock_with_card +] +``` + +```ruby Ruby +entrances = seam.acs.entrances.list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +card_entrances = entrances.select do |e| + e.can_unlock_with_card +end +``` + +```php PHP +$entrances = $seam->acs->entrances->list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +$cardEntrances = array_filter( + $entrances, + fn($e) => $e->can_unlock_with_card +); +``` + +```csharp C# +var entrances = seam.Acs.Entrances.List( + acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +var cardEntrances = entrances + .Where(e => e.CanUnlockWithCard) + .ToList(); +``` + +```java Java +var entrances = seam.acs().entrances().list( + AcsEntrancesListRequest.builder() + .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339") + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/acs/entrances/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +}' +``` + + + +## Step 2: Create an Access Grant with a Key Card + +Create an [Access Grant](/use-cases/granting-access/index) specifying `card` as the requested access method mode. + + + +```javascript JavaScript +const accessGrant = await seam.accessGrants.create({ + user_identity_id: '22222222-2222-2222-2222-222222222222', + acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'], + requested_access_methods: [ + { mode: 'card' } + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` + +```python Python +access_grant = seam.access_grants.create( + user_identity_id="22222222-2222-2222-2222-222222222222", + acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods=[{"mode": "card"}], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z", +) +``` + +```ruby Ruby +access_grant = seam.access_grants.create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [{ mode: "card" }], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` + +```php PHP +$accessGrant = $seam->access_grants->create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [["mode" => "card"]], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` + +```csharp C# +var accessGrant = seam.AccessGrants.Create( + userIdentityId: "22222222-2222-2222-2222-222222222222", + acsEntranceIds: new List + { + "f74e4879-5991-4e2f-a368-888983dcfbfc" + }, + requestedAccessMethods: new List + { + new RequestedAccessMethod { Mode = "card" } + }, + startsAt: "2025-07-13T15:00:00.000Z", + endsAt: "2025-07-16T11:00:00.000Z" +); +``` + +```java Java +var accessGrant = seam.accessGrants().create( + AccessGrantsCreateRequest.builder() + .userIdentityId("22222222-2222-2222-2222-222222222222") + .acsEntranceIds(List.of( + "f74e4879-5991-4e2f-a368-888983dcfbfc" + )) + .requestedAccessMethods(List.of( + RequestedAccessMethod.builder() + .mode("card") + .build() + )) + .startsAt("2025-07-13T15:00:00.000Z") + .endsAt("2025-07-16T11:00:00.000Z") + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + "requested_access_methods": [{ "mode": "card" }], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + + + +## Step 3: Deliver the Key Card + +Retrieve the access method and check the `is_encoding_required` property to determine whether you need to encode the card or whether the system assigns it automatically. + + + +```javascript JavaScript +const accessMethod = await seam.accessMethods.get({ + access_method_id: + accessGrant.requested_access_methods[0].created_access_method_ids[0], +}) + +console.log(accessMethod.is_encoding_required) +``` + +```python Python +access_method = seam.access_methods.get( + access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +print(access_method.is_encoding_required) +``` + +```ruby Ruby +access_method = seam.access_methods.get( + access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +puts access_method.is_encoding_required +``` + +```php PHP +$accessMethod = $seam->access_methods->get( + access_method_id: $accessGrant->requested_access_methods[0]->created_access_method_ids[0] +); + +echo $accessMethod->is_encoding_required; +``` + +```csharp C# +var accessMethod = seam.AccessMethods.Get( + accessMethodId: accessGrant.RequestedAccessMethods[0].CreatedAccessMethodIds[0] +); + +Console.WriteLine(accessMethod.IsEncodingRequired); +``` + +```java Java +var accessMethod = seam.accessMethods().get( + AccessMethodsGetRequest.builder() + .accessMethodId( + accessGrant.getRequestedAccessMethods().get(0).getCreatedAccessMethodIds().get(0) + ) + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +}' +``` + + + +**Output:** + +```json +{ + "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "display_name": "Key Card", + "mode": "card", + "is_issued": false, + "is_encoding_required": true, + ... +} +``` + +--- + +### Encoding Cards + +If `is_encoding_required` is `true`, you must encode the credential onto a physical card using a card encoder before handing the card to your user. + +Use the Seam API to encode the card: + + + +```javascript JavaScript +const actionAttempt = await seam.accessMethods.encode({ + access_method_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', + acs_encoder_id: 'encoder-001', +}) +``` + +```python Python +action_attempt = seam.access_methods.encode( + access_method_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890", + acs_encoder_id="encoder-001", +) +``` + +```ruby Ruby +action_attempt = seam.access_methods.encode( + access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + acs_encoder_id: "encoder-001" +) +``` + +```php PHP +$actionAttempt = $seam->access_methods->encode( + access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + acs_encoder_id: "encoder-001" +); +``` + +```csharp C# +var actionAttempt = seam.AccessMethods.Encode( + accessMethodId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + acsEncoderId: "encoder-001" +); +``` + +```java Java +var actionAttempt = seam.accessMethods().encode( + AccessMethodsEncodeRequest.builder() + .accessMethodId("a1b2c3d4-e5f6-7890-abcd-ef1234567890") + .acsEncoderId("encoder-001") + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/encode' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "acs_encoder_id": "encoder-001" +}' +``` + + + +Once encoding is complete, the access method's `is_encoding_required` property changes to `false` and `is_issued` changes to `true`. Hand the encoded card to your user. + +For the complete card encoding workflow, including listing encoders and scanning cards, see [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index). + +--- + +### Assigning Cards + +If `is_encoding_required` is `false`, the ACS assigns the credential to a card automatically — no physical encoding step is needed. This is common with systems that use pre-registered or cloud-managed cards. + +In this case, once `is_issued` is `true`, the card is ready. Hand the assigned card to your user. + +## Next Steps + +- [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index) — Complete guide to encoding and scanning cards. +- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) — Learn how to deliver all access method types to your users. +- [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — Learn more about specifying devices, entrances, and spaces. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. diff --git a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx new file mode 100644 index 000000000..c990bcb25 --- /dev/null +++ b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx @@ -0,0 +1,308 @@ +--- +title: 'Using Mobile Keys' +description: >- + Learn how to create an Access Grant with a mobile key access method and + deliver it through your mobile app using the Seam mobile SDKs. +--- + +Mobile keys let your users unlock doors by tapping a button in your mobile app. When you request a `mobile_key` access method in an Access Grant, Seam issues a mobile credential that you deliver through your own app using the Seam mobile SDKs. Each mobile key also includes an [Instant Key](/capability-guides/instant-keys/index) URL for immediate access without an app download. + +Mobile keys work with: + +- **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and other ACS platforms that support BLE-based mobile credentials. Specify entrances with `acs_entrance_ids` or use `space_ids`. + +## Before You Begin + +To use mobile keys, you need: + +- A [Seam API key](https://console.seam.co) +- A connected ACS with BLE-capable lock hardware +- Mobile key licenses or subscriptions activated for your ACS (requirements vary by system — see your [system integration guide](https://docs.seam.co/latest/device-and-system-integration-guides#access-control-systems)) +- A [user identity](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities) representing the person who will receive the mobile key +- An entrance that supports mobile keys (`can_unlock_with_mobile_key` is `true`) + + + If you plan to build a mobile app that delivers mobile keys, see + [Mobile Access](/capability-guides/mobile-access/index) for the complete + SDK integration guide. If you just want to share a link for instant access, + see [Using Instant Keys](/use-cases/granting-access/using-instant-keys) instead. + + +## Step 1: Verify Entrance Support + +List the entrances for your ACS and confirm that `can_unlock_with_mobile_key` is `true`. + + + +```javascript JavaScript +const entrances = await seam.acs.entrances.list({ + acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', +}) + +const mobileKeyEntrances = entrances.filter( + (e) => e.can_unlock_with_mobile_key +) +``` + +```python Python +entrances = seam.acs.entrances.list( + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +mobile_key_entrances = [ + e for e in entrances if e.can_unlock_with_mobile_key +] +``` + +```ruby Ruby +entrances = seam.acs.entrances.list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +mobile_key_entrances = entrances.select do |e| + e.can_unlock_with_mobile_key +end +``` + +```php PHP +$entrances = $seam->acs->entrances->list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +$mobileKeyEntrances = array_filter( + $entrances, + fn($e) => $e->can_unlock_with_mobile_key +); +``` + +```csharp C# +var entrances = seam.Acs.Entrances.List( + acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +var mobileKeyEntrances = entrances + .Where(e => e.CanUnlockWithMobileKey) + .ToList(); +``` + +```java Java +var entrances = seam.acs().entrances().list( + AcsEntrancesListRequest.builder() + .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339") + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/acs/entrances/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +}' +``` + + + +## Step 2: Create an Access Grant with a Mobile Key + +Create an [Access Grant](/use-cases/granting-access/index) specifying `mobile_key` as the requested access method mode. + + + +```javascript JavaScript +const accessGrant = await seam.accessGrants.create({ + user_identity_id: '22222222-2222-2222-2222-222222222222', + acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'], + requested_access_methods: [ + { mode: 'mobile_key' } + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` + +```python Python +access_grant = seam.access_grants.create( + user_identity_id="22222222-2222-2222-2222-222222222222", + acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods=[{"mode": "mobile_key"}], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z", +) +``` + +```ruby Ruby +access_grant = seam.access_grants.create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [{ mode: "mobile_key" }], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` + +```php PHP +$accessGrant = $seam->access_grants->create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + requested_access_methods: [["mode" => "mobile_key"]], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` + +```csharp C# +var accessGrant = seam.AccessGrants.Create( + userIdentityId: "22222222-2222-2222-2222-222222222222", + acsEntranceIds: new List + { + "f74e4879-5991-4e2f-a368-888983dcfbfc" + }, + requestedAccessMethods: new List + { + new RequestedAccessMethod { Mode = "mobile_key" } + }, + startsAt: "2025-07-13T15:00:00.000Z", + endsAt: "2025-07-16T11:00:00.000Z" +); +``` + +```java Java +var accessGrant = seam.accessGrants().create( + AccessGrantsCreateRequest.builder() + .userIdentityId("22222222-2222-2222-2222-222222222222") + .acsEntranceIds(List.of( + "f74e4879-5991-4e2f-a368-888983dcfbfc" + )) + .requestedAccessMethods(List.of( + RequestedAccessMethod.builder() + .mode("mobile_key") + .build() + )) + .startsAt("2025-07-13T15:00:00.000Z") + .endsAt("2025-07-16T11:00:00.000Z") + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"], + "requested_access_methods": [{ "mode": "mobile_key" }], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + + + +## Step 3: Deliver the Mobile Key + +Once the access method is issued, retrieve it to get the `client_session_id`. Use this value to initialize the Seam mobile SDK on your user's device so they can unlock doors from your app. + + + +```javascript JavaScript +const accessMethod = await seam.accessMethods.get({ + access_method_id: + accessGrant.requested_access_methods[0].created_access_method_ids[0], +}) + +console.log(accessMethod.client_session_id) +console.log(accessMethod.instant_key_url) +``` + +```python Python +access_method = seam.access_methods.get( + access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +print(access_method.client_session_id) +print(access_method.instant_key_url) +``` + +```ruby Ruby +access_method = seam.access_methods.get( + access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +puts access_method.client_session_id +puts access_method.instant_key_url +``` + +```php PHP +$accessMethod = $seam->access_methods->get( + access_method_id: $accessGrant->requested_access_methods[0]->created_access_method_ids[0] +); + +echo $accessMethod->client_session_id; +echo $accessMethod->instant_key_url; +``` + +```csharp C# +var accessMethod = seam.AccessMethods.Get( + accessMethodId: accessGrant.RequestedAccessMethods[0].CreatedAccessMethodIds[0] +); + +Console.WriteLine(accessMethod.ClientSessionId); +Console.WriteLine(accessMethod.InstantKeyUrl); +``` + +```java Java +var accessMethod = seam.accessMethods().get( + AccessMethodsGetRequest.builder() + .accessMethodId( + accessGrant.getRequestedAccessMethods().get(0).getCreatedAccessMethodIds().get(0) + ) + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" +}' +``` + + + +**Output:** + +```json +{ + "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", + "display_name": "Mobile Key", + "mode": "mobile_key", + "is_issued": true, + "issued_at": "2025-06-16T16:55:03.924353Z", + "client_session_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... +} +``` + +Use the `client_session_id` to look up the client session token, then pass it to the Seam mobile SDK to initialize your user's mobile app. For the complete mobile SDK integration guide, see [Mobile Access](/capability-guides/mobile-access/index). + + + Every mobile key also includes an `instant_key_url`. You can share this URL + with your user as an alternative or backup access method — no app download + required. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys). + + +## Next Steps + +- [Mobile Access](/capability-guides/mobile-access/index) — Complete guide to building a mobile app with the Seam mobile SDKs. +- [Using Instant Keys](/use-cases/granting-access/using-instant-keys) — Share the Instant Key URL included with every mobile key. +- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) — Learn how to deliver all access method types to your users. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. diff --git a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx new file mode 100644 index 000000000..4916bf024 --- /dev/null +++ b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx @@ -0,0 +1,357 @@ +--- +title: 'Using PIN Codes' +description: >- + Learn how to create an Access Grant with a PIN code access method and deliver + the code to your user. +--- + +PIN codes are the simplest access method. When you request a `code` access method in an Access Grant, Seam programs a PIN code onto the lock. Your user enters the code on the lock's keypad to unlock the door. + +PIN codes work with: + +- **Standalone smart locks** — August, Yale, Schlage, Lockly, TTLock, Tedee, igloohome, and other connected locks. Specify the locks with `device_ids`. +- **Access control systems** — Salto KS, Salto Space, Brivo, dormakaba, and other ACS platforms that support PIN-based credentials. Specify entrances with `acs_entrance_ids` or group access points into spaces and use `space_ids`. + +## Before You Begin + +To use PIN codes, you need: + +- A [Seam API key](https://console.seam.co) +- One or more connected devices or ACS entrances that support PIN codes +- For standalone smart locks: confirm that `can_program_online_access_codes` is `true` on the device +- For ACS entrances: confirm that `can_unlock_with_code` is `true` on the entrance + +## Step 1: Verify Device or Entrance Support + +### Standalone Smart Locks + +List your devices and confirm that `can_program_online_access_codes` is `true`. + + + +```javascript JavaScript +const devices = await seam.devices.list() + +const pinCapableDevices = devices.filter( + (d) => d.can_program_online_access_codes +) +``` + +```python Python +devices = seam.devices.list() + +pin_capable_devices = [ + d for d in devices if d.can_program_online_access_codes +] +``` + +```ruby Ruby +devices = seam.devices.list + +pin_capable_devices = devices.select do |d| + d.can_program_online_access_codes +end +``` + +```php PHP +$devices = $seam->devices->list(); + +$pinCapableDevices = array_filter( + $devices, + fn($d) => $d->can_program_online_access_codes +); +``` + +```csharp C# +var devices = seam.Devices.List(); + +var pinCapableDevices = devices + .Where(d => d.CanProgramOnlineAccessCodes) + .ToList(); +``` + +```java Java +var devices = seam.devices().list( + DevicesListRequest.builder().build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/devices/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{}' +``` + + + +### ACS Entrances + +List the entrances for your ACS and confirm that `can_unlock_with_code` is `true`. + + + +```javascript JavaScript +const entrances = await seam.acs.entrances.list({ + acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', +}) + +const codeEntrances = entrances.filter( + (e) => e.can_unlock_with_code +) +``` + +```python Python +entrances = seam.acs.entrances.list( + acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +code_entrances = [ + e for e in entrances if e.can_unlock_with_code +] +``` + +```ruby Ruby +entrances = seam.acs.entrances.list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +) + +code_entrances = entrances.select do |e| + e.can_unlock_with_code +end +``` + +```php PHP +$entrances = $seam->acs->entrances->list( + acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +$codeEntrances = array_filter( + $entrances, + fn($e) => $e->can_unlock_with_code +); +``` + +```csharp C# +var entrances = seam.Acs.Entrances.List( + acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +); + +var codeEntrances = entrances + .Where(e => e.CanUnlockWithCode) + .ToList(); +``` + +```java Java +var entrances = seam.acs().entrances().list( + AcsEntrancesListRequest.builder() + .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339") + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/acs/entrances/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" +}' +``` + + + +## Step 2: Create an Access Grant with a PIN Code + +Create an [Access Grant](/use-cases/granting-access/index) specifying `code` as the requested access method mode. You can target devices, entrances, or spaces. + + + +```javascript JavaScript +const accessGrant = await seam.accessGrants.create({ + user_identity_id: '22222222-2222-2222-2222-222222222222', + device_ids: ['6ba7b811-9dad-11d1-80b4-00c04fd430c8'], + requested_access_methods: [ + { mode: 'code' } + ], + starts_at: '2025-07-13T15:00:00.000Z', + ends_at: '2025-07-16T11:00:00.000Z', +}) +``` + +```python Python +access_grant = seam.access_grants.create( + user_identity_id="22222222-2222-2222-2222-222222222222", + device_ids=["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods=[{"mode": "code"}], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z", +) +``` + +```ruby Ruby +access_grant = seam.access_grants.create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods: [{ mode: "code" }], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +) +``` + +```php PHP +$accessGrant = $seam->access_grants->create( + user_identity_id: "22222222-2222-2222-2222-222222222222", + device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods: [["mode" => "code"]], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" +); +``` + +```csharp C# +var accessGrant = seam.AccessGrants.Create( + userIdentityId: "22222222-2222-2222-2222-222222222222", + deviceIds: new List + { + "6ba7b811-9dad-11d1-80b4-00c04fd430c8" + }, + requestedAccessMethods: new List + { + new RequestedAccessMethod { Mode = "code" } + }, + startsAt: "2025-07-13T15:00:00.000Z", + endsAt: "2025-07-16T11:00:00.000Z" +); +``` + +```java Java +var accessGrant = seam.accessGrants().create( + AccessGrantsCreateRequest.builder() + .userIdentityId("22222222-2222-2222-2222-222222222222") + .deviceIds(List.of( + "6ba7b811-9dad-11d1-80b4-00c04fd430c8" + )) + .requestedAccessMethods(List.of( + RequestedAccessMethod.builder() + .mode("code") + .build() + )) + .startsAt("2025-07-13T15:00:00.000Z") + .endsAt("2025-07-16T11:00:00.000Z") + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/create' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "user_identity_id": "22222222-2222-2222-2222-222222222222", + "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + "requested_access_methods": [{ "mode": "code" }], + "starts_at": "2025-07-13T15:00:00.000Z", + "ends_at": "2025-07-16T11:00:00.000Z" +}' +``` + + + + + In a sandbox workspace, PIN codes are issued almost instantly. On real + devices, issuance can take a few moments. Poll the access method until + `is_issued` is `true` or watch for the `access_method.issued` event. + + +## Step 3: Retrieve the PIN Code + +Once the access method is issued, retrieve it to get the code. Share the code with your user through text, email, or your application. + + + +```javascript JavaScript +const accessMethod = await seam.accessMethods.get({ + access_method_id: + accessGrant.requested_access_methods[0].created_access_method_ids[0], +}) + +console.log(accessMethod.code) // => "1234" +``` + +```python Python +access_method = seam.access_methods.get( + access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +print(access_method.code) # => "1234" +``` + +```ruby Ruby +access_method = seam.access_methods.get( + access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0] +) + +puts access_method.code # => "1234" +``` + +```php PHP +$accessMethod = $seam->access_methods->get( + access_method_id: $accessGrant->requested_access_methods[0]->created_access_method_ids[0] +); + +echo $accessMethod->code; // => "1234" +``` + +```csharp C# +var accessMethod = seam.AccessMethods.Get( + accessMethodId: accessGrant.RequestedAccessMethods[0].CreatedAccessMethodIds[0] +); + +Console.WriteLine(accessMethod.Code); // => "1234" +``` + +```java Java +var accessMethod = seam.accessMethods().get( + AccessMethodsGetRequest.builder() + .accessMethodId( + accessGrant.getRequestedAccessMethods().get(0).getCreatedAccessMethodIds().get(0) + ) + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" +}' +``` + + + +**Output:** + +```json +{ + "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "display_name": "PIN Code", + "mode": "code", + "is_issued": true, + "issued_at": "2025-06-16T16:55:03.924353Z", + "code": "1234", + ... +} +``` + +## Next Steps + +- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) — Learn how to deliver all access method types to your users. +- [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — Learn more about specifying devices, entrances, and spaces. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. From 433057f27a7630ca2fc99392a3e7eb2d4838d350 Mon Sep 17 00:00:00 2001 From: dawnho Date: Tue, 9 Jun 2026 23:38:00 -0700 Subject: [PATCH 02/36] feat: add assignment_required event to issuance tracking Mention access_method.assignment_required event in the lifecycle events section. This event fires when an access method requires manual assignment to an ACS user before it can be issued. Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/creating-an-access-grant.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx index ff95d9c63..e7f677f47 100644 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx +++ b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx @@ -1412,8 +1412,9 @@ You can also watch for the following Access Grant and access method events: - `access_grant.access_granted_to_door` — Seam has granted access to a specific door. - `access_grant.access_granted_to_all_doors` — Seam has granted access to all requested doors. -- `access_method.card_encoding_required` — A card access method needs to be encoded onto a plastic card. - `access_method.issued` — An access method is ready to deliver to your user. +- `access_method.card_encoding_required` — A card access method needs to be encoded onto a plastic card. +- `access_method.assignment_required` — An access method requires manual assignment to an ACS user before it can be issued. This can occur when Seam cannot automatically match the access method to an existing user identity in the access control system. Example `access_method.card_encoding_required` event payload: From 8ed780bb61b9a0c5e8defd2c3a384d03f3afa908 Mon Sep 17 00:00:00 2001 From: dawnho Date: Tue, 9 Jun 2026 23:46:10 -0700 Subject: [PATCH 03/36] feat: remove access_grant door events from issuance tracking Keep the event list focused on access method issuance events only. Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/creating-an-access-grant.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx index e7f677f47..6dbffed04 100644 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx +++ b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx @@ -1408,10 +1408,8 @@ $seam->access_methods->get( ### Watch for Lifecycle Events -You can also watch for the following Access Grant and access method events: +You can also watch for the following access method events: -- `access_grant.access_granted_to_door` — Seam has granted access to a specific door. -- `access_grant.access_granted_to_all_doors` — Seam has granted access to all requested doors. - `access_method.issued` — An access method is ready to deliver to your user. - `access_method.card_encoding_required` — A card access method needs to be encoded onto a plastic card. - `access_method.assignment_required` — An access method requires manual assignment to an ACS user before it can be issued. This can occur when Seam cannot automatically match the access method to an existing user identity in the access control system. From e46c45dd5f8fee6ca9a1f4f69c67714f07233d65 Mon Sep 17 00:00:00 2001 From: dawnho Date: Tue, 9 Jun 2026 23:46:43 -0700 Subject: [PATCH 04/36] feat: add card_assignment_required event to issuance tracking Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/creating-an-access-grant.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx index 6dbffed04..07ada1254 100644 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx +++ b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx @@ -1413,6 +1413,7 @@ You can also watch for the following access method events: - `access_method.issued` — An access method is ready to deliver to your user. - `access_method.card_encoding_required` — A card access method needs to be encoded onto a plastic card. - `access_method.assignment_required` — An access method requires manual assignment to an ACS user before it can be issued. This can occur when Seam cannot automatically match the access method to an existing user identity in the access control system. +- `access_method.card_assignment_required` — A card access method requires manual assignment to a physical card before it can be issued. Example `access_method.card_encoding_required` event payload: From ff91bb6af91b660532394bbecb2fc768c6ae4c19 Mon Sep 17 00:00:00 2001 From: dawnho Date: Tue, 9 Jun 2026 23:48:30 -0700 Subject: [PATCH 05/36] feat: remove assignment_required event from issuance tracking Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/creating-an-access-grant.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx index 07ada1254..df2b615e0 100644 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx +++ b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx @@ -1412,7 +1412,6 @@ You can also watch for the following access method events: - `access_method.issued` — An access method is ready to deliver to your user. - `access_method.card_encoding_required` — A card access method needs to be encoded onto a plastic card. -- `access_method.assignment_required` — An access method requires manual assignment to an ACS user before it can be issued. This can occur when Seam cannot automatically match the access method to an existing user identity in the access control system. - `access_method.card_assignment_required` — A card access method requires manual assignment to a physical card before it can be issued. Example `access_method.card_encoding_required` event payload: From e7332b5f54b3d4373d175d6dd84a18fceb0dec5d Mon Sep 17 00:00:00 2001 From: dawnho Date: Tue, 9 Jun 2026 23:56:01 -0700 Subject: [PATCH 06/36] fix: broken link to user identities page in using-key-cards Change directory-style link to file-style .md link to match actual file path. Co-Authored-By: Claude Opus 4.6 --- docs/guides/use-cases/granting-access/using-key-cards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/use-cases/granting-access/using-key-cards.md b/docs/guides/use-cases/granting-access/using-key-cards.md index 6ffe1211b..f4ccec037 100644 --- a/docs/guides/use-cases/granting-access/using-key-cards.md +++ b/docs/guides/use-cases/granting-access/using-key-cards.md @@ -18,7 +18,7 @@ To use key cards, you need: - A [Seam API key](https://console.seam.co) - A connected ACS that supports card-based credentials -- A [user identity](../../capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities/) representing the person who will receive the card +- A [user identity](../../capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities.md) representing the person who will receive the card - An entrance that supports card access (`can_unlock_with_card` is `true`) - For encoding: a compatible card encoder connected to Seam (see [Working with Card Encoders and Scanners](../../low-level-apis/access-systems/working-with-card-encoders-and-scanners/)) From de97ece0d1bad2814db8b2b51c22a9255142172a Mon Sep 17 00:00:00 2001 From: dawnho Date: Tue, 9 Jun 2026 23:59:40 -0700 Subject: [PATCH 07/36] =?UTF-8?q?feat:=20complete=20nav=20restructure=20?= =?UTF-8?q?=E2=80=94=20add=20managing=20pages,=20remove=20old=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The squash commit missed these changes. This commit: - Adds managing-access-grants.mdx and managing-access-methods.mdx - Removes 6 consolidated pages (quick start, delivering overview, retrieving, updating, revoking, deleting) - Updates docs.json nav with delivery group and managing pages - Updates SUMMARY.mdx to match - Adds redirects for all removed pages Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/SUMMARY.mdx | 8 +- mintlify-docs/docs.json | 73 +- .../access-grant-quick-start.mdx | 798 ------ .../deleting-an-access-grant.mdx | 76 - .../delivering-access-methods.mdx | 302 --- .../managing-access-grants.mdx | 240 ++ .../managing-access-methods.mdx | 236 ++ ...eving-access-grants-and-access-methods.mdx | 2146 ----------------- .../revoking-an-access-method.mdx | 76 - .../updating-an-access-grant.mdx | 108 - 10 files changed, 539 insertions(+), 3524 deletions(-) delete mode 100644 mintlify-docs/use-cases/granting-access/access-grant-quick-start.mdx delete mode 100644 mintlify-docs/use-cases/granting-access/deleting-an-access-grant.mdx delete mode 100644 mintlify-docs/use-cases/granting-access/delivering-access-methods.mdx create mode 100644 mintlify-docs/use-cases/granting-access/managing-access-grants.mdx create mode 100644 mintlify-docs/use-cases/granting-access/managing-access-methods.mdx delete mode 100644 mintlify-docs/use-cases/granting-access/retrieving-access-grants-and-access-methods.mdx delete mode 100644 mintlify-docs/use-cases/granting-access/revoking-an-access-method.mdx delete mode 100644 mintlify-docs/use-cases/granting-access/updating-an-access-grant.mdx diff --git a/mintlify-docs/SUMMARY.mdx b/mintlify-docs/SUMMARY.mdx index 22efce500..a24a6cc44 100644 --- a/mintlify-docs/SUMMARY.mdx +++ b/mintlify-docs/SUMMARY.mdx @@ -9,19 +9,15 @@ title: 'Table of contents' ## Use Cases - [Granting Access](./use-cases/granting-access/index) - - [Access Grant Quick Start](./use-cases/granting-access/access-grant-quick-start) - [Creating an Access Grant](./use-cases/granting-access/creating-an-access-grant) - - [Delivering Access Methods](./use-cases/granting-access/delivering-access-methods) - [Using PIN Codes](./use-cases/granting-access/using-pin-codes) - [Using Mobile Keys](./use-cases/granting-access/using-mobile-keys) - [Using Instant Keys](./use-cases/granting-access/using-instant-keys) - [Using Key Cards](./use-cases/granting-access/using-key-cards) - [Using Cloud Keys](./use-cases/granting-access/using-cloud-keys) + - [Managing Access Grants](./use-cases/granting-access/managing-access-grants) + - [Managing Access Methods](./use-cases/granting-access/managing-access-methods) - [Reservation Access Grants](./use-cases/granting-access/reservation-access-grants) - - [Retrieving Access Grants and Access Methods](./use-cases/granting-access/retrieving-access-grants-and-access-methods) - - [Updating an Access Grant](./use-cases/granting-access/updating-an-access-grant) - - [Revoking an Access Method](./use-cases/granting-access/revoking-an-access-method) - - [Deleting an Access Grant](./use-cases/granting-access/deleting-an-access-grant) ## Core Concepts diff --git a/mintlify-docs/docs.json b/mintlify-docs/docs.json index d37103cd9..3b117c6bf 100644 --- a/mintlify-docs/docs.json +++ b/mintlify-docs/docs.json @@ -52,19 +52,20 @@ "group": "Granting Access", "pages": [ "use-cases/granting-access/index", - "use-cases/granting-access/access-grant-quick-start", "use-cases/granting-access/creating-an-access-grant", - "use-cases/granting-access/delivering-access-methods", - "use-cases/granting-access/using-pin-codes", - "use-cases/granting-access/using-mobile-keys", - "use-cases/granting-access/using-instant-keys", - "use-cases/granting-access/using-key-cards", - "use-cases/granting-access/using-cloud-keys", - "use-cases/granting-access/reservation-access-grants", - "use-cases/granting-access/retrieving-access-grants-and-access-methods", - "use-cases/granting-access/updating-an-access-grant", - "use-cases/granting-access/revoking-an-access-method", - "use-cases/granting-access/deleting-an-access-grant" + { + "group": "Delivering Access Methods", + "pages": [ + "use-cases/granting-access/using-pin-codes", + "use-cases/granting-access/using-mobile-keys", + "use-cases/granting-access/using-instant-keys", + "use-cases/granting-access/using-key-cards", + "use-cases/granting-access/using-cloud-keys" + ] + }, + "use-cases/granting-access/managing-access-grants", + "use-cases/granting-access/managing-access-methods", + "use-cases/granting-access/reservation-access-grants" ] } ] @@ -3143,6 +3144,54 @@ { "source": "/use-cases/granting-access/creating-an-access-grant-using-entrances", "destination": "/use-cases/granting-access/creating-an-access-grant" + }, + { + "source": "/use-cases/granting-access/access-grant-quick-start", + "destination": "/use-cases/granting-access/creating-an-access-grant" + }, + { + "source": "/use-cases/granting-access/delivering-access-methods", + "destination": "/use-cases/granting-access/creating-an-access-grant" + }, + { + "source": "/use-cases/granting-access/retrieving-access-grants-and-access-methods", + "destination": "/use-cases/granting-access/creating-an-access-grant" + }, + { + "source": "/use-cases/granting-access/updating-an-access-grant", + "destination": "/use-cases/granting-access/managing-access-grants" + }, + { + "source": "/use-cases/granting-access/deleting-an-access-grant", + "destination": "/use-cases/granting-access/managing-access-grants" + }, + { + "source": "/use-cases/granting-access/revoking-an-access-method", + "destination": "/use-cases/granting-access/managing-access-methods" + }, + { + "source": "/capability-guides/access-grants/access-grant-quick-start", + "destination": "/use-cases/granting-access/creating-an-access-grant" + }, + { + "source": "/capability-guides/access-grants/delivering-access-methods", + "destination": "/use-cases/granting-access/creating-an-access-grant" + }, + { + "source": "/capability-guides/access-grants/retrieving-access-grants-and-access-methods", + "destination": "/use-cases/granting-access/creating-an-access-grant" + }, + { + "source": "/capability-guides/access-grants/updating-an-access-grant", + "destination": "/use-cases/granting-access/managing-access-grants" + }, + { + "source": "/capability-guides/access-grants/deleting-an-access-grant", + "destination": "/use-cases/granting-access/managing-access-grants" + }, + { + "source": "/capability-guides/access-grants/revoking-an-access-method", + "destination": "/use-cases/granting-access/managing-access-methods" } ], "openapi": [ diff --git a/mintlify-docs/use-cases/granting-access/access-grant-quick-start.mdx b/mintlify-docs/use-cases/granting-access/access-grant-quick-start.mdx deleted file mode 100644 index ffa9a619f..000000000 --- a/mintlify-docs/use-cases/granting-access/access-grant-quick-start.mdx +++ /dev/null @@ -1,798 +0,0 @@ ---- -title: 'Access Grant Quick Start' -description: 'Create your first Access Grant to give a user scheduled access to a set of access points with Seam.' ---- - -In this quick start, create an Access Grant to give a user access to a set of access points. Access Grants are the default and recommended way to grant access to any physical space, irrespective of the locking hardware—standalone smart locks, access control systems, or a mix of both. With a single command you can define the "who, where, when, and how" for assigning a user access. - - - **Starting with a standalone smart lock?** The fastest first success is a - single device and a PIN code: see the [Seam Quick Start](../../quickstart), - which creates an Access Grant on a sandbox August lock, or [Creating an Access - Grant](/use-cases/granting-access/creating-an-access-grant#using-device-ids). This quick - start walks through the more advanced access system (ACS) path, including key - cards, mobile keys, and Instant Keys. - - -In addition, this quick start shows you that, with Access Grants, it's easy to issue users access through multiple types of access methods, such as key cards, PIN codes, mobile keys, and Instant Keys. - - - Seam Instant Keys are the fastest way to share access. You can send them as - links through text or email, with no app download required. For details, see - [Instant Keys](/capability-guides/instant-keys/index). - - ---- - -## Before You Begin - -Before you begin this quick start, perform the following steps: - -1. [Connect](/core-concepts/workspaces/index#connecting-virtual-devices) an access system to Seam. - - In this quick start, you can use a Seam virtual access system in a sandbox workspace, for example, the [virtual Salto Space access system](https://docs.seam.co/latest/device-and-system-integration-guides/salto-proaccess-space-access-system/sandbox-salto-space-access-control-system). - - For instructions, see [Connect an Access System to Seam](/low-level-apis/access-systems/connect-an-acs-to-seam/index). - -2. Install a Seam SDK and create an API key. - - For instructions, see [Installation](https://docs.seam.co/latest/api/installation) and [API Keys](../../core-concepts/authentication/api-keys). - ---- - -## Overview - -This quick start walks you through the following basic steps: - -1. Create an Access Grant. - - This Access Grant defines the following characteristics: - - User identity: The user to whom you want to grant access. - - Entrances: The set of entrances or other access points to which you want to grant the user access. - - Access schedule: The starting and ending times for access. - - Access methods: The modes of access, including key cards, PIN codes, mobile keys, and Instant Keys. - - For instructions, see [Step 1: Create an Access Grant](#step-1-create-an-access-grant). - -2. Poll for access method status changes or monitor for Access Grant and access method lifecycle events. - - These properties and events let you know what your next step is. They also alert you to when you can deliver the access methods to your user. - - For instructions, see [Step 2: Poll for Status Changes or Monitor for Lifecycle Events](#step-2-poll-for-status-changes-or-monitor-for-lifecycle-events). - -3. Deliver the created access methods to your user. - - The delivery method depends on the access method. - - For instructions, see [Step 3: Deliver the Access Methods](#step-3-deliver-the-access-methods). - -:rocket: Let's get started! - ---- - -## Step 1: Create an Access Grant - -Create an Access Grant to define the "who, where, when, and how" for assigning a user access to entrances and other access points. In this example, suppose that you want to grant a user named Jane Doe access for a three-day period. Jane needs to access two doors. To show how to create multiple access methods, this example issues Jane a key card and a mobile key that includes an Instant Key. - -1. Find the access system ID. - 1. In the top navigation pane of [Seam Console](https://console.seam.co/), click **ACS Systems**. - 2. On the **Access Systems** page, locate the access system that you connected to Seam. - 3. In the **acs_system_id** column for the access system, click the ID to copy it. - 4. Store this access system ID for future use. -2. Create the Access Grant, as follows: - -**Code:** - - - -```javascript JavaScript -import { Seam } from 'seam' - -const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY. - -// Identify the IDs of the entrances to which -// you want to grant access. -const entrances = await seam.acs.entrances.list({ - // Use the access system ID that you copied in the previous step. - acs_system_id: acsSystemId, -}) - -// Create the Access Grant. -const accessGrant = await seam.accessGrants.create({ - // Create a new user identity to represent your user. - user_identity: { - full_name: 'Jane Doe', - email_address: 'jane.doe@example.com', - phone_number: '+15555551000', - }, - // Specify the IDs of the entrances to which you want to grant access. - acs_entrance_ids: [ - entrances[0].acs_entrance_id, - entrances[1].acs_entrance_id, - ], - // Specify the access methods that you want to issue. - requested_access_methods: [{ mode: 'card' }, { mode: 'mobile_key' }], - // Specify the access schedule. - starts_at: '2025-08-01T15:00:00.000Z', - ends_at: '2025-08-04T11:00:00.000Z', -}) -``` - -```curl cURL -# Identify the IDs of the entrances to which -# you want to grant access. -# Use the access system ID that you copied in the previous step. -mapfile -t entrances < <( - curl -s --request POST "https://connect.getseam.com/acs/entrances/list" \ - --header "Authorization: Bearer $SEAM_API_KEY" \ - --header "Content-Type: application/json" \ - --data "{\"acs_system_id\": \"$acs_system_id\"}" | - jq -c '.acs_entrances[]' -) - -# Create the Access Grant. -# In this command: -# - Create a new user identity to represent your user. -# - Specify the IDs of the entrances to which you want to grant access. -# - Specify the access methods that you want to issue. -# - Specify the access schedule. -access_grant=$(curl --include --request POST "https://connect.getseam.com/access_grants/create" \ - -H "Authorization: Bearer $SEAM_API_KEY" \ - -H 'Content-Type: application/json' \ - -d "{ - \"user_identity\": { - \"full_name\": \"Jane Doe\", - \"email_address\": \"jane.doe@example.com\", - \"phone_number\": \"+15555551000\" - }, - \"acs_entrance_ids\": [ - \"$(echo ${entrances[0]} | jq -r '.acs_entrance_id')\", - \"$(echo ${entrances[1]} | jq -r '.acs_entrance_id')\" - ], - \"requested_access_methods\": [ - { - \"mode\": \"card\" - }, - { - \"mode\": \"mobile_key\" - } - ], - \"starts_at\": \"2025-08-01T15:00:00.000Z\", - \"ends_at\": \"2025-08-04T11:00:00.000Z\" -}") -``` - -```python Python -from seam import Seam - -seam = Seam() # Seam automatically uses your exported SEAM_API_KEY. - -# Identify the IDs of the entrances to which -# you want to grant access. -entrances = seam.acs.entrances.list( - # Use the access system ID that you copied in the previous step. - acs_system_id=acs_system_id -) - -# Create the Access Grant. -access_grant = seam.access_grants.create( - # Create a new user identity to represent your user. - user_identity={ - "full_name": "Jane Doe", - "email_address": "jane.doe@example.com", - "phone_number": "+15555551000" - }, - # Specify the IDs of the entrances to which you want to grant access. - acs_entrance_ids=[ - entrances[0].acs_entrance_id, - entrances[1].acs_entrance_id - ], - - # Specify the access methods that you want to issue. - requested_access_methods=[ - {"mode": "card"}, - {"mode": "mobile_key"} - ], - # Specify the access schedule. - starts_at="2025-08-01T15:00:00.000Z", - ends_at="2025-08-04T11:00:00.000Z" -) -``` - -```ruby Ruby -require "seam" - -seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY. - -# Identify the IDs of the entrances to which -# you want to grant access. -entrances = seam.acs.entrances.list( - # Use the access system ID that you copied in the previous step. - acs_system_id: acs_system_id -) - -# Create the Access Grant. -access_grant = seam.access_grants.create( - # Create a new user identity to represent your user. - user_identity: { - full_name: "Jane Doe", - email_address: "jane.doe@example.com", - phone_number: "+15555551000" - }, - # Specify the IDs of the entrances to which you want to grant access. - acs_entrance_ids: [ - entrances[0].acs_entrance_id, - entrances[1].acs_entrance_id - ], - # Specify the access methods that you want to issue. - requested_access_methods: [ - { mode: "card" }, - { mode: "mobile_key" } - ], - # Specify the access schedule. - starts_at: "2025-08-01T15:00:00.000Z", - ends_at: "2025-08-04T11:00:00.000Z" -) -``` - -```php PHP -acs->entrances->list( - // Use the access system ID that you copied in the previous step. - acs_system_id: $acs_system_id -); - -// Create the Access Grant. -$access_grant = $seam->access_grants->create( - // Create a new user identity to represent your user. - user_identity: [ - "full_name" => "Jane Doe", - "email_address" => "jane.doe@example.com", - "phone_number" => "+15555551000" - ], - // Specify the IDs of the entrances to which you want to grant access. - acs_entrance_ids: [ - $entrances[0]->acs_entrance_id, - $entrances[1]->acs_entrance_id - ], - // Specify the access methods that you want to issue. - requested_access_methods: [ - ["mode" => "card"], - ["mode" => "mobile_key"] - ], - // Specify the access schedule. - starts_at: '2025-08-01T15:00:00.000Z', - ends_at: '2025-08-04T11:00:00.000Z' -); -``` - -```csharp C# -// Coming soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - access_grant_id: '6d74aefc-5712-4a8b-82c1-73a51ae60b87', - user_identity_id: '8cc2633a-54ca-455a-8a2b-77e6a1fc4fee', - starts_at: '2025-08-01T15:00:00.000Z', - ends_at: '2025-08-04T11:00:00.000Z' - instant_key_url: 'https://ik.seam.co/ABCXYZ', - requested_access_methods: [ - { - display_name: 'Plastic card', - mode: 'card', - created_access_method_ids: ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - created_at: '2025-06-16T16:54:19.946606Z' - }, - { - display_name: 'Mobile key', - mode: 'mobile_key', - created_access_method_ids: ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - created_at: '2025-06-16T16:54:21.946606Z' - } - ], - ... -} -``` - -```json cURL -{ - "access_grant":{ - "access_grant_id":"6d74aefc-5712-4a8b-82c1-73a51ae60b87", - "user_identity_id":"8cc2633a-54ca-455a-8a2b-77e6a1fc4fee", - "starts_at":"2025-08-01T15:00:00.000Z", - "ends_at":"2025-08-04T11:00:00.000Z", - "instant_key_url":"https://ik.seam.co/ABCXYZ", - "requested_access_methods":[ - { - "display_name":"Plastic Card", - "mode":"card", - "created_access_method_ids":["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - "created_at":"2025-06-16T16:54:19.946606Z" - }, - { - "display_name":"Mobile Key", - "mode":"mobile_key", - "created_access_method_ids":["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - "created_at":"2025-06-16T16:54:21.946606Z" - } - ], - ... - }, - "ok":true -} -``` - -```python Python -AccessGrant( - access_grant_id='6d74aefc-5712-4a8b-82c1-73a51ae60b87', - user_identity_id='8cc2633a-54ca-455a-8a2b-77e6a1fc4fee', - starts_at='2025-08-01T15:00:00.000Z', - ends_at='2025-08-04T11:00:00.000Z', - instant_key_url='https://ik.seam.co/ABCXYZ', - requested_access_methods=[ - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"] - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_at": "2025-06-16T16:54:21.946606Z", - "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"] - } - ], - ... -) -``` - -```ruby Ruby -"Plastic card", - "mode"=>"card", - "created_access_method_ids"=>["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - "created_at"=>"2025-06-16T16:54:19.946606Z" - }, - { - "display_name"=>"Mobile key", - "mode"=>"mobile_key", - "created_access_method_ids"=>["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - "created_at"=>"2025-06-16T16:54:21.946606Z" - } - ] - ... -> -``` - -```php PHP -{ - "access_grant_id":"6d74aefc-5712-4a8b-82c1-73a51ae60b87", - "user_identity_id":"8cc2633a-54ca-455a-8a2b-77e6a1fc4fee", - "starts_at":"2025-08-01T15:00:00.000Z", - "ends_at":"2025-08-04T11:00:00.000Z", - "instant_key_url":"https://ik.seam.co/ABCXYZ", - "requested_access_methods":[ - { - "display_name":"Plastic Card", - "mode":"card", - "created_access_method_ids":["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"], - "created_at":"2025-06-16T16:54:19.946606Z" - }, - { - "display_name":"Mobile Key", - "mode":"mobile_key", - "created_access_method_ids":["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - "created_at":"2025-06-16T16:54:21.946606Z" - } - ], - ... -} -``` - -```json C# -// Coming soon! -``` - - - ---- - -## Step 2: Poll for Status Changes or Monitor for Lifecycle Events - -Once you've created an Access Grant with one or more access methods, poll the created access methods for status changes or watch for Access Grant and access method lifecycle events. The `access_method.is_issued` property and event let you know when an access method is ready to deliver to your user. - -### Poll for Status Changes - -To poll the created access methods, get these access methods by ID and look for the following status changes: - -- If `access_method.is_encoding_required` is `true`, you must encode the card access method onto a plastic key card. Once you've encoded the access method onto a card, this property changes to `false`. -- When an access method is ready to be delivered to a user, `access_method.is_issued` changes to `true`. For a card access method, `access_method.is_issued` changes to `true` after you encode the plastic card. You can also view the `access_method.issued_at` property to learn when the access method was issued. - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.get({ - access_method_id: 'c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f', -}) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -}' -``` - -```python Python -seam.access_methods.get( - access_method_id = "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -```ruby Ruby -seam.access_methods.get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -```php PHP -$seam->access_methods->get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... -} -``` - -```json cURL -{ - "access_method": { - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": true, - "is_issued": false, - "issued_at": null, - ... - }, - "ok": true -} -``` - -```json Python -AccessMethod( - access_method_id="c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - display_name="Plastic Card", - mode="card", - created_at="2025-06-16T16:54:19.946606Z", - is_card_encoding_required=true, - is_issued=false, - issued_at=null, - ... -) -``` - -```json Ruby -{ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -} -``` - -```json PHP -[ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => true, - "is_issued" => false, - "issued_at" => null, - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -### Monitor for Lifecycle Events - -Watch for the following events that include the IDs of the created Access Grant and access methods: - -- `access_grant.access_granted_to_door` -- `access_grant.access_granted_to_all_doors` -- `access_method.card_encoding_required` -- `access_method.issued` - -These events tell you what to do next. For example, if you've created a card access method, `access_method.card_encoding_required` lets you know that you need to encode the access method onto a plastic card. `access_grant.access_granted_to_all_doors` tells you that Seam has successfully created all the access methods that you requested through the Access Grant. `access_method.issued` indicates that you can now deliver the access method to your user. - -The following example shows the payload for an `access_method.card_encoding_required` event: - -```json -{ - "event_id": "22222222-3333-4444-5555-666666666666", - "event_description": "An access method representing a physical card requires encoding.", - "event_type": "access_method.card_encoding_required", - "acs_system_id": "11111111-1111-1111-1111-111111111111", - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - ... -} -``` - ---- - -## Step 3: Deliver the Access Methods - -Once the access methods are ready to deliver to your user, retrieve each access method by ID. Remember, the returned access grant includes the IDs of all the requested access methods. Then, deliver each access method to your user. The delivery mechanism varies for different access method modes. - - - If you've created an Access Grant that includes a mobile key, the access grant - also contains the corresponding Instant Key URL, for added efficiency. In this - case, you do not need to retrieve the access method. Instead, you can identify - the Instant Key URL directly from the returned Access Grant. - - -### Get an Access Method - -Retrieve each access method that you created as part of the Access Grant. Note that the set of relevant properties for an access method varies based on the mode, such as `card`, `code`, or `mobile_key`. - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.get({ - access_method_id: 'c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f', -}) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -}' -``` - -```python Python -seam.access_methods.get( - access_method_id = "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -```ruby Ruby -seam.access_methods.get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -) -``` - -```php PHP -$seam->access_methods->get( - access_method_id: "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": false, - "is_issued": true, - "issued_at": "2025-06-16T16:55:03.924353Z", - ... -} -``` - -```json cURL -{ - "access_method": { - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required": false, - "is_issued": true, - "issued_at": "2025-06-16T16:55:03.924353Z", - ... - }, - "ok": true -} -``` - -```json Python -AccessMethod( - access_method_id="c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - display_name="Plastic Card", - mode="card", - created_at="2025-06-16T16:54:19.946606Z", - is_card_encoding_required=false, - is_issued=true, - issued_at="2025-06-16T16:55:03.924353Z", - ... -) -``` - -```json Ruby -{ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => false, - "is_issued" => true, - "issued_at" => "2025-06-16T16:55:03.924353Z", - ... -} -``` - -```json PHP -[ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_card_encoding_required" => false, - "is_issued" => true, - "issued_at" => "2025-06-16T16:55:03.924353Z", - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -### Deliver the Access Method to Your User - -The way in which you deliver an access method depends on the mode of access. The following table describes the delivery mechanisms: - - - - - - - - - - - - - - - - - - - - - - - - - - -
Access Method ModeDelivery Mechanism
PIN code - You can retrieve the access method by ID. The returned access method - resource includes the code that you can share with your - user. -
Plastic key card - Some access systems require you to encode plastic key cards. In this - case, the access method's is_encoding_required property is{' '} - true. You can use the Seam API or Seam Console to encode - and scan the cards. For details, see{' '} - - Working with Card Encoders and Scanners - - .
- Once you've encoded the card, the access method's{' '} - is_encoding_required property changes to false - , and its is_issued property changes to true. - The card is ready to be delivered to your user. -
Mobile key - You deliver a mobile key to your user within your own mobile app that - you develop using the Seam mobile SDKs. For mobile keys, the access - method includes a client_session_token property that you - can use to identify the client session and client session token that you - need to initialize the Seam client on your user's mobile device. Then, - your user simply taps a button in your app to unlock the door. For - details, see{' '} - Mobile Access. -
Instant Key - Each mobile key that you create also includes an Instant Key. Seam - Instant Keys are the most streamlined mobile access experience available - today. Both the Access Grant and the mobile key access method include - the instant_key_url property. You deliver this URL to your - user by sending it through text or email. There's no app download - required. You can also embed an Instant Key in your own app. For - details, see{' '} - Instant Keys and{' '} - - Delivering Instant Keys - - . -
- ---- - -## Next Steps - -Now that you've created your first Access Grant, learn more about Access Grants. - -- [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) -- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) -- [Access Grants API Reference](https://docs.seam.co/latest/api/access_grants/) -- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) diff --git a/mintlify-docs/use-cases/granting-access/deleting-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/deleting-an-access-grant.mdx deleted file mode 100644 index f3a54d80c..000000000 --- a/mintlify-docs/use-cases/granting-access/deleting-an-access-grant.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: 'Deleting an Access Grant' -description: 'Learn how to delete an Access Grant.' ---- - -To delete an Access Grant: - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.delete({ - access_grant_id: '403ea27b-af76-4a48-ace9-8f9498f4c25c', -}) -``` - -```curl cURL -curl --include --request POST "https://connect.getseam.com/access_grants/delete" \ - --header "Authorization: Bearer $SEAM_API_KEY" \ - --json @- <access_grants->delete( - access_grant_id: "403ea27b-af76-4a48-ace9-8f9498f4c25c" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -// void -``` - -```curl cURL -{} -``` - -```python Python -None -``` - -```ruby Ruby -nil -``` - -```php PHP - -``` - -```json C# -// Coming Soon! -``` - - diff --git a/mintlify-docs/use-cases/granting-access/delivering-access-methods.mdx b/mintlify-docs/use-cases/granting-access/delivering-access-methods.mdx deleted file mode 100644 index dd2fc4312..000000000 --- a/mintlify-docs/use-cases/granting-access/delivering-access-methods.mdx +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: 'Delivering Access Methods' -description: 'Learn how to deliver key cards, PIN codes, mobile keys, and Instant Keys to your users.' ---- - -The `access_method.is_issued` property and event let you know when an access method is ready to deliver to your user. Once an access method is ready to deliver, retrieve the access method by ID. Remember, the returned Access Grant includes the IDs of all the requested access methods. Then, deliver the access method to your user. The delivery mechanism varies for different access method modes. - - - If you've created an Access Grant that includes a mobile key, the Access Grant - also contains the corresponding Instant Key URL, for added efficiency. In this - case, you do not need to retrieve the access method. Instead, you can identify - the Instant Key URL directly from the returned Access Grant. - - -This topic describes how to deliver the various access method modes. - ---- - -## PIN Codes - -You can retrieve the access method by ID. The returned access method resource includes the `code` that you can share with your user. - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.get({ - access_method_id: 'f47ac10b-58cc-4372-a567-0e02b2c3d479', -}) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" -}' -``` - -```python Python -seam.access_methods.get( - access_method_id = "f47ac10b-58cc-4372-a567-0e02b2c3d479" -) -``` - -```ruby Ruby -seam.access_methods.get( - access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" -) -``` - -```php PHP -$seam->access_methods->get( - access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name": "PIN Code", - "mode": "code", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_issued": true, - "issued_at": "2025-06-16T16:55:03.924353Z", - "code": "1234", - ... -} -``` - -```json cURL -{ - "access_method": { - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name": "PIN Code", - "mode": "code", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_issued": true, - "issued_at": "2025-06-16T16:55:03.924353Z", - "code": "1234", - ... - }, - "ok": true -} -``` - -```json Python -AccessMethod( - access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", - display_name="PIN Code", - mode="code", - created_at="2025-06-16T16:54:19.946606Z", - is_issued=true, - issued_at="2025-06-16T16:55:03.924353Z", - code="1234", - ... -) -``` - -```json Ruby -{ - "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name" => "PIN Code", - "mode" => "code", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_issued" => true, - "issued_at" => "2025-06-16T16:55:03.924353Z", - "code" => "1234", - ... -} -``` - -```json PHP -[ - "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name" => "PIN Code", - "mode" => "code", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_issued" => true, - "issued_at" => "2025-06-16T16:55:03.924353Z", - "code" => "1234", - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Plastic Key Cards - -Some access systems require you to encode plastic key cards. In this case, the access method's `is_encoding_required` property is `true`. You can use the Seam API or Seam Console to encode and scan the cards. For details, see [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index). - -Once you've encoded the card, the access method's `is_encoding_required` property changes to `false`, and its `is_issued` property changes to `true`. The card is ready to be delivered to your user. - ---- - -## Mobile Keys - -You deliver a mobile key to your user within your own mobile app that you develop using the Seam mobile SDKs. For mobile keys, the access method includes a `client_session_id` property that you can use to identify the client session and client session token that you need to initialize the Seam client on your user's mobile device. Then, your user simply taps a button in your app to unlock the door. For details, see [Mobile Access](/capability-guides/mobile-access/index). - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.get({ - access_method_id: '6ba7b810-9dad-11d1-80b4-00c04fd430c8', -}) -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" -}' -``` - -```python Python -seam.access_methods.get( - access_method_id = "6ba7b810-9dad-11d1-80b4-00c04fd430c8" -) -``` - -```ruby Ruby -seam.access_methods.get( - access_method_id: "6ba7b810-9dad-11d1-80b4-00c04fd430c8" -) -``` - -```php PHP -$seam->access_methods->get( - access_method_id: "6ba7b810-9dad-11d1-80b4-00c04fd430c8" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```json JavaScript -{ - "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_issued": true, - "issued_at": "2025-06-16T16:55:03.924353Z", - "client_session_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... -} -``` - -```json cURL -{ - "access_method": { - "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", - "display_name": "Mobile Key", - "mode": "mobile_key", - "created_at": "2025-06-16T16:54:19.946606Z", - "is_issued": true, - "issued_at": "2025-06-16T16:55:03.924353Z", - "client_session_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... - }, - "ok": true -} -``` - -```json Python -AccessMethod( - access_method_id="6ba7b810-9dad-11d1-80b4-00c04fd430c8", - display_name="Mobile Key", - mode="mobile_key", - created_at="2025-06-16T16:54:19.946606Z", - is_issued=true, - issued_at="2025-06-16T16:55:03.924353Z", - client_session_id="3f2504e0-4f89-11d3-9a0c-0305e82c3301", - instant_key_url="https://ik.seam.co/ABCXYZ", - ... -) -``` - -```json Ruby -{ - "access_method_id" => "6ba7b810-9dad-11d1-80b4-00c04fd430c8", - "display_name" => "Mobile Key", - "mode" => "mobile_key", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_issued" => true, - "issued_at" => "2025-06-16T16:55:03.924353Z", - "client_session_id" => "3f2504e0-4f89-11d3-9a0c-0305e82c3301", - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -} -``` - -```json PHP -[ - "access_method_id" => "6ba7b810-9dad-11d1-80b4-00c04fd430c8", - "display_name" => "Mobile Key", - "mode" => "mobile_key", - "created_at" => "2025-06-16T16:54:19.946606Z", - "is_issued" => true, - "issued_at" => "2025-06-16T16:55:03.924353Z", - "client_session_id" => "3f2504e0-4f89-11d3-9a0c-0305e82c3301", - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Instant Keys - -Each mobile key that you create also includes an Instant Key. Seam Instant Keys are the most streamlined mobile access experience available today. Both the Access Grant and the mobile key access method include the `instant_key_url` property. You deliver this URL to your user by sending it through text or email. No app download is required. You can also embed an Instant Key in your own app. For details, see [Instant Keys](/capability-guides/instant-keys/index) and [Delivering Instant Keys](../../capability-guides/instant-keys/delivering-instant-keys). - ---- - -## Cloud Keys - -Cloud keys provide a web-based unlock experience. Your user opens a web pass or taps an unlock button in your app, and the door unlocks over the internet through the ACS cloud connection. Each unlock is attributed to the specific user identity in the ACS audit trail — not recorded as a generic system action. - -To unlock an entrance on behalf of a user, call `/access_methods/unlock_door` with the cloud key `access_method_id` and the `acs_entrance_id`. - -For the complete workflow — including verifying entrance support and creating an Access Grant with a cloud key — see [Using Cloud Keys](/use-cases/granting-access/using-cloud-keys). diff --git a/mintlify-docs/use-cases/granting-access/managing-access-grants.mdx b/mintlify-docs/use-cases/granting-access/managing-access-grants.mdx new file mode 100644 index 000000000..f13bd15c5 --- /dev/null +++ b/mintlify-docs/use-cases/granting-access/managing-access-grants.mdx @@ -0,0 +1,240 @@ +--- +title: "Managing Access Grants" +description: "Update the schedule or resources on an Access Grant, or delete a grant entirely when access should end." +--- + +After you've [created an Access Grant](/use-cases/granting-access/creating-an-access-grant), circumstances change — a guest extends their stay, a contractor's scope expands to a new building, or a reservation is cancelled. This page covers how to update or delete an Access Grant to handle these situations. + +--- + +## Updating an Access Grant + +Use `access_grants.update` when you need to change _when_ or _where_ a person has access. Common scenarios include: + +- **Extended stay:** A hotel guest extends their checkout from Friday to Sunday — update `ends_at`. +- **Early access:** A contractor needs to start a day earlier — update `starts_at`. +- **Scope change:** A resident moves from Unit 101 to Unit 205 — update `device_ids`, `space_ids`, or `acs_entrance_ids`. + +### Updating the Schedule + +Pass `starts_at` and/or `ends_at` to change the access window. The new schedule applies to all access methods under the grant. + + + +```python Python +# Guest extended their stay — push checkout to Sunday +seam.access_grants.update( + access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ends_at="2025-07-18T11:00:00.000Z", +) +``` + +```javascript JavaScript +// Guest extended their stay — push checkout to Sunday +await seam.accessGrants.update({ + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ends_at: "2025-07-18T11:00:00.000Z", +}); +``` + +```ruby Ruby +# Guest extended their stay — push checkout to Sunday +seam.access_grants.update( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ends_at: "2025-07-18T11:00:00.000Z" +) +``` + +```php PHP +// Guest extended their stay — push checkout to Sunday +$seam->access_grants->update( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + ends_at: "2025-07-18T11:00:00.000Z" +); +``` + +```csharp C# +// Coming soon! +``` + +```java Java +// Coming soon! +``` + +```bash cURL (bash) +# Guest extended their stay — push checkout to Sunday +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/update' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "ends_at": "2025-07-18T11:00:00.000Z" + }' +``` + + + +### Updating Resources + +Pass `device_ids`, `space_ids`, or `acs_entrance_ids` to change _where_ the person has access. For example, if a resident moves units, update the grant to point to the new space instead of deleting and recreating it. + + + +```python Python +# Resident moved from Unit 101 to Unit 205 +seam.access_grants.update( + access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + space_ids=["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"], +) +``` + +```javascript JavaScript +// Resident moved from Unit 101 to Unit 205 +await seam.accessGrants.update({ + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + space_ids: ["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"], +}); +``` + +```ruby Ruby +# Resident moved from Unit 101 to Unit 205 +seam.access_grants.update( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + space_ids: ["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"] +) +``` + +```php PHP +// Resident moved from Unit 101 to Unit 205 +$seam->access_grants->update( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + space_ids: ["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"] +); +``` + +```csharp C# +// Coming soon! +``` + +```java Java +// Coming soon! +``` + +```bash cURL (bash) +# Resident moved from Unit 101 to Unit 205 +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/update' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "space_ids": ["b0c5d5e0-7f0a-4f1b-8e3d-unit-205-space"] + }' +``` + + + +--- + +## Re-issuance After an Update + +When you update an Access Grant, Seam needs to re-program the credentials on the affected devices. During this process, each access method temporarily becomes invalid. + +### What happens to each access method + +1. Seam emits an `access_method.revoked` event and sets `is_issued` to `false`. The credential is no longer valid on the device. +2. Seam re-programs the credential with the updated schedule or resources. +3. Once the credential is active again, the next step depends on the mode: + +| Mode | What happens | Event | +| --- | --- | --- | +| **PIN code** | The code value stays the same. Seam updates the valid time window on the lock automatically. | `access_method.reissued` | +| **Mobile key** | Seam updates the credential automatically. | `access_method.reissued` | +| **Cloud key** | Seam updates the credential automatically. | `access_method.reissued` | +| **Card** | The physical card must be re-encoded with the new credential. | `access_method.card_encoding_required`, then `access_method.reissued` after encoding | + + +For cards, you'll need to [re-encode the card](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods) before the updated credential takes effect. Plan for this if your workflow relies on physical cards — the guest will need to visit the front desk. + + +### Listening for re-issuance events + +Use [webhooks](/developer-tools/webhooks) or poll `access_methods.list` to track when access methods become valid again after an update: + +- **`access_method.revoked`** — The credential has been invalidated and is being re-programmed. The access method's `is_issued` is `false`. +- **`access_method.card_encoding_required`** — (Cards only) The new credential is ready but needs to be encoded onto the physical card. +- **`access_method.reissued`** — The credential is active again. The access method's `is_issued` is `true`. + +--- + +## Deleting an Access Grant + +Delete an Access Grant when a person's access should end entirely — for example, when a guest checks out, an employee is offboarded, or a contractor's engagement ends. Deleting the grant removes **all** access methods under it at once. + + + +```python Python +# Guest checked out — revoke all access +seam.access_grants.delete( + access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b" +) +``` + +```javascript JavaScript +// Guest checked out — revoke all access +await seam.accessGrants.delete({ + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", +}); +``` + +```ruby Ruby +# Guest checked out — revoke all access +seam.access_grants.delete( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b" +) +``` + +```php PHP +// Guest checked out — revoke all access +$seam->access_grants->delete( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b" +); +``` + +```csharp C# +// Coming soon! +``` + +```java Java +// Coming soon! +``` + +```bash cURL (bash) +# Guest checked out — revoke all access +curl -X 'POST' \ + 'https://connect.getseam.com/access_grants/delete' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{"access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b"}' +``` + + + +Seam emits an `access_grant.deleted` event and an `access_method.deleted` event for each access method that was removed. + + +To revoke a single access method while keeping the rest active (for example, disabling a lost key card but keeping the guest's PIN code), use [`access_methods.delete`](/use-cases/granting-access/managing-access-methods#revoking-an-access-method) instead. + + +### Delete vs. Update + +| Scenario | Action | +| --- | --- | +| Guest checks out, employee offboards — all access should end | **Delete** the Access Grant | +| Guest extends stay, schedule changes | **Update** `starts_at` / `ends_at` | +| Person moves to a different unit or building | **Update** `device_ids`, `space_ids`, or `acs_entrance_ids` | +| One credential is lost but the person still needs access | [**Delete** the access method](/use-cases/granting-access/managing-access-methods#revoking-an-access-method), not the grant | diff --git a/mintlify-docs/use-cases/granting-access/managing-access-methods.mdx b/mintlify-docs/use-cases/granting-access/managing-access-methods.mdx new file mode 100644 index 000000000..3a49f5aa6 --- /dev/null +++ b/mintlify-docs/use-cases/granting-access/managing-access-methods.mdx @@ -0,0 +1,236 @@ +--- +title: "Managing Access Methods" +description: "Add new access methods to an existing Access Grant or revoke individual credentials." +--- + +After you've [created an Access Grant](/use-cases/granting-access/creating-an-access-grant) and delivered the initial credentials, you may need to add new access methods or revoke existing ones — without changing the grant itself. + +This page covers operations on **individual access methods**. To update the schedule, resources, or delete the entire grant, see [Managing Access Grants](/use-cases/granting-access/managing-access-grants). + +--- + +## Adding an Access Method + +A single Access Grant can have multiple access methods. You can add new ones at any time — for example: + +- A guest originally received a PIN code but now also wants a **mobile key** for hands-free entry. +- A building manager needs to issue a **key card** for a contractor who doesn't have a smartphone. +- An office tenant wants to add a **cloud key** so their front desk app can trigger remote unlocks for visitors. + +The new access method inherits the schedule and resources from the existing Access Grant automatically. + + + +```python Python +# Guest wants a mobile key in addition to their PIN code +access_method = seam.access_methods.create( + access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + mode="mobile_key", +) +``` + +```javascript JavaScript +// Guest wants a mobile key in addition to their PIN code +const accessMethod = await seam.accessMethods.create({ + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + mode: "mobile_key", +}); +``` + +```ruby Ruby +# Guest wants a mobile key in addition to their PIN code +access_method = seam.access_methods.create( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + mode: "mobile_key" +) +``` + +```php PHP +// Guest wants a mobile key in addition to their PIN code +$access_method = $seam->access_methods->create( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + mode: "mobile_key" +); +``` + +```csharp C# +// Coming soon! +``` + +```java Java +// Coming soon! +``` + +```bash cURL (bash) +# Guest wants a mobile key in addition to their PIN code +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "mode": "mobile_key" + }' +``` + + + +Once created, deliver the new access method the same way as any other — see the delivery guides for [PIN codes](/use-cases/granting-access/using-pin-codes), [mobile keys](/use-cases/granting-access/using-mobile-keys), [key cards](/use-cases/granting-access/using-key-cards), [instant keys](/use-cases/granting-access/using-instant-keys), or [cloud keys](/use-cases/granting-access/using-cloud-keys). + +--- + +## Revoking an Access Method + +Revoke a single access method when you need to disable one credential while keeping the rest active. Common scenarios include: + +- A guest **lost their key card** — revoke the card but keep their PIN code working so they're not locked out. +- A tenant's **phone was stolen** — revoke the mobile key immediately while a replacement is set up. +- A temporary **cloud key** was issued for a one-time visitor and is no longer needed. + + + +```python Python +# Guest lost their key card — revoke it, keep PIN active +seam.access_methods.delete( + access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479" +) +``` + +```javascript JavaScript +// Guest lost their key card — revoke it, keep PIN active +await seam.accessMethods.delete({ + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479", +}); +``` + +```ruby Ruby +# Guest lost their key card — revoke it, keep PIN active +seam.access_methods.delete( + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" +) +``` + +```php PHP +// Guest lost their key card — revoke it, keep PIN active +$seam->access_methods->delete( + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" +); +``` + +```csharp C# +// Coming soon! +``` + +```java Java +// Coming soon! +``` + +```bash cURL (bash) +# Guest lost their key card — revoke it, keep PIN active +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/delete' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{"access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}' +``` + + + +Seam removes the credential from the device or access system and emits an `access_method.deleted` event. Other access methods under the same Access Grant are unaffected. + + +To revoke **all** access for a person at once — for example, on checkout or offboarding — [delete the entire Access Grant](/use-cases/granting-access/managing-access-grants#deleting-an-access-grant) instead. + + +### Revoke and Replace + +A common pattern is to revoke a compromised credential and immediately issue a replacement: + + + +```python Python +# Revoke the lost card +seam.access_methods.delete( + access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479" +) + +# Issue a replacement card under the same grant +new_card = seam.access_methods.create( + access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + mode="card", +) +``` + +```javascript JavaScript +// Revoke the lost card +await seam.accessMethods.delete({ + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479", +}); + +// Issue a replacement card under the same grant +const newCard = await seam.accessMethods.create({ + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + mode: "card", +}); +``` + +```ruby Ruby +# Revoke the lost card +seam.access_methods.delete( + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" +) + +# Issue a replacement card under the same grant +new_card = seam.access_methods.create( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + mode: "card" +) +``` + +```php PHP +// Revoke the lost card +$seam->access_methods->delete( + access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" +); + +// Issue a replacement card under the same grant +$new_card = $seam->access_methods->create( + access_grant_id: "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + mode: "card" +); +``` + +```csharp C# +// Coming soon! +``` + +```java Java +// Coming soon! +``` + +```bash cURL (bash) +# Revoke the lost card +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/delete' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{"access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}' + +# Issue a replacement card under the same grant +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/create' \ + -H 'accept: application/json' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", + "mode": "card" + }' +``` + + + +The replacement card will need to be [encoded](/use-cases/granting-access/using-key-cards) before it's ready for the guest. diff --git a/mintlify-docs/use-cases/granting-access/retrieving-access-grants-and-access-methods.mdx b/mintlify-docs/use-cases/granting-access/retrieving-access-grants-and-access-methods.mdx deleted file mode 100644 index a0fa6a23b..000000000 --- a/mintlify-docs/use-cases/granting-access/retrieving-access-grants-and-access-methods.mdx +++ /dev/null @@ -1,2146 +0,0 @@ ---- -title: 'Retrieving Access Grants and Access Methods' -description: 'Learn how to list and get Access Grants and access methods.' ---- - -You can list all Access Grants, and you can also filter the list by one or more of the following properties: - -- `acs_entrance_id` -- `acs_system_id` -- `space_id` -- `user_identity_id` - -You can also list all access methods for a specified Access Grant. In addition, you can get a specific Access Grant or access method by its ID. - ---- - -## List Access Grants - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.list() -``` - -```curl cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -```python Python -seam.access_grants.list() -``` - -```ruby Ruby -seam.access_grants.list() -``` - -```php PHP -$seam->access_grants->list(); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -[ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... -] -``` - -```curl cURL -{ - "access_grants": [ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... - ], - "ok": true -} -``` - -```python Python -[ - AccessGrant( - 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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ], - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ], - }, - { - "display_name": "Mobile Key", - "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", - } - ), - ... -] -``` - -```ruby Ruby -[ - { - "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", - mode: "code", - created_at: "2025-06-16T16:54:17.946606Z", - created_access_method_ids: ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"], - }, - { - display_name: "Plastic Card", - mode: "card", - created_at: "2025-06-16T16:54:19.946606Z", - created_access_method_ids: ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - }, - { - display_name: "Mobile Key", - 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", - }, - }, - ... -] -``` - -```php PHP -[ - [ - "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", - "mode" => "code", - "created_at" => "2025-06-16T16:54:17.946606Z", - "created_access_method_ids" => [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - ], - ], - [ - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "created_access_method_ids" => [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - ], - ], - [ - "display_name" => "Mobile Key", - "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", - ], - ], - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -### List Access Grants for an Entrance - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.list({ - acs_entrance_id: '2673b363-4748-4a64-8075-f669c862ec74', -}) -``` - -```curl cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "acs_entrance_id": "2673b363-4748-4a64-8075-f669c862ec74" -}' -``` - -```python Python -seam.access_grants.list( - acs_entrance_id="2673b363-4748-4a64-8075-f669c862ec74" -) -``` - -```ruby Ruby -seam.access_grants.list( - acs_entrance_id: "2673b363-4748-4a64-8075-f669c862ec74" -) -``` - -```php PHP -$seam->access_grants->list( - acs_entrance_id: "2673b363-4748-4a64-8075-f669c862ec74" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -[ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... -] -``` - -```curl cURL -{ - "access_grants": [ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... - ], - "ok": true -} -``` - -```python Python -[ - AccessGrant( - 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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ], - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ], - }, - { - "display_name": "Mobile Key", - "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", - } - ), - ... -] -``` - -```ruby Ruby -[ - { - "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", - mode: "code", - created_at: "2025-06-16T16:54:17.946606Z", - created_access_method_ids: ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"], - }, - { - display_name: "Plastic Card", - mode: "card", - created_at: "2025-06-16T16:54:19.946606Z", - created_access_method_ids: ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - }, - { - display_name: "Mobile Key", - 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", - }, - }, - ... -] -``` - -```php PHP -[ - [ - "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", - "mode" => "code", - "created_at" => "2025-06-16T16:54:17.946606Z", - "created_access_method_ids" => [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - ], - ], - [ - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "created_access_method_ids" => [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - ], - ], - [ - "display_name" => "Mobile Key", - "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", - ], - ], - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -### List Access Grants for an Access System - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.list({ - acs_system_id: '9f169742-048a-4105-84e3-bd1e0f9dc790', -}) -``` - -```curl cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "acs_system_id": "9f169742-048a-4105-84e3-bd1e0f9dc790" -}' -``` - -```python Python -seam.access_grants.list( - acs_system_id="9f169742-048a-4105-84e3-bd1e0f9dc790" -) -``` - -```ruby Ruby -seam.access_grants.list( - acs_system_id: "9f169742-048a-4105-84e3-bd1e0f9dc790" -) -``` - -```php PHP -$seam->access_grants->list( - acs_system_id: "9f169742-048a-4105-84e3-bd1e0f9dc790" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -[ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... -] -``` - -```curl cURL -{ - "access_grants": [ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... - ], - "ok": true -} -``` - -```python Python -[ - AccessGrant( - 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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ], - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ], - }, - { - "display_name": "Mobile Key", - "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", - } - ), - ... -] -``` - -```ruby Ruby -[ - { - "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", - mode: "code", - created_at: "2025-06-16T16:54:17.946606Z", - created_access_method_ids: ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"], - }, - { - display_name: "Plastic Card", - mode: "card", - created_at: "2025-06-16T16:54:19.946606Z", - created_access_method_ids: ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - }, - { - display_name: "Mobile Key", - 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", - }, - }, - ... -] -``` - -```php PHP -[ - [ - "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", - "mode" => "code", - "created_at" => "2025-06-16T16:54:17.946606Z", - "created_access_method_ids" => [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - ], - ], - [ - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "created_access_method_ids" => [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - ], - ], - [ - "display_name" => "Mobile Key", - "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", - ], - ], - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -### List Access Grants for a Space - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.list({ - space_id: '1d20c47d-3cc0-41ca-9917-bc798d071543', -}) -``` - -```curl cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "space_id": "1d20c47d-3cc0-41ca-9917-bc798d071543" -}' -``` - -```python Python -seam.access_grants.list( - space_id="1d20c47d-3cc0-41ca-9917-bc798d071543" -) -``` - -```ruby Ruby -seam.access_grants.list( - space_id: "1d20c47d-3cc0-41ca-9917-bc798d071543" -) -``` - -```php PHP -$seam->access_grants->list( - space_id: "1d20c47d-3cc0-41ca-9917-bc798d071543" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -[ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... -] -``` - -```curl cURL -{ - "access_grants": [ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... - ], - "ok": true -} -``` - -```python Python -[ - AccessGrant( - 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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ], - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ], - }, - { - "display_name": "Mobile Key", - "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", - } - ), - ... -] -``` - -```ruby Ruby -[ - { - "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", - mode: "code", - created_at: "2025-06-16T16:54:17.946606Z", - created_access_method_ids: ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"], - }, - { - display_name: "Plastic Card", - mode: "card", - created_at: "2025-06-16T16:54:19.946606Z", - created_access_method_ids: ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - }, - { - display_name: "Mobile Key", - 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", - }, - }, - ... -] -``` - -```php PHP -[ - [ - "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", - "mode" => "code", - "created_at" => "2025-06-16T16:54:17.946606Z", - "created_access_method_ids" => [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - ], - ], - [ - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "created_access_method_ids" => [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - ], - ], - [ - "display_name" => "Mobile Key", - "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", - ], - ], - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - -### List Access Grants for a User Identity - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.list({ - user_identity_id: 'f7620fcf-d92f-471e-b97e-3806daeebd40', -}) -``` - -```curl cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "user_identity_id": "f7620fcf-d92f-471e-b97e-3806daeebd40" -}' -``` - -```python Python -seam.access_grants.list( - user_identity_id="f7620fcf-d92f-471e-b97e-3806daeebd40" -) -``` - -```ruby Ruby -seam.access_grants.list( - user_identity_id: "f7620fcf-d92f-471e-b97e-3806daeebd40" -) -``` - -```php PHP -$seam->access_grants->list( - user_identity_id: "f7620fcf-d92f-471e-b97e-3806daeebd40" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -[ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... -] -``` - -```curl cURL -{ - "access_grants": [ - { - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ] - }, - { - "display_name": "Mobile Key", - "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" - } - }, - ... - ], - "ok": true -} -``` - -```python Python -[ - AccessGrant( - 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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d" - ], - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f" - ], - }, - { - "display_name": "Mobile Key", - "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", - } - ), - ... -] -``` - -```ruby Ruby -[ - { - "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", - mode: "code", - created_at: "2025-06-16T16:54:17.946606Z", - created_access_method_ids: ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"], - }, - { - display_name: "Plastic Card", - mode: "card", - created_at: "2025-06-16T16:54:19.946606Z", - created_access_method_ids: ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - }, - { - display_name: "Mobile Key", - 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", - }, - }, - ... -] -``` - -```php PHP -[ - [ - "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", - "mode" => "code", - "created_at" => "2025-06-16T16:54:17.946606Z", - "created_access_method_ids" => [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - ], - ], - [ - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "created_access_method_ids" => [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - ], - ], - [ - "display_name" => "Mobile Key", - "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", - ], - ], - ... -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## List Access Methods for an Access Grant - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.list({ - access_grant_id: '9072ebcd-95f3-4e4b-8f2f-10053911533b', -}) -``` - -```curl cURL -curl --include --request POST "https://connect.getseam.com/access_methods/list" \ - --header "Authorization: Bearer $SEAM_API_KEY" \ - --json @- <access_methods->list( - access_grant_id: "9072ebcd-95f3-4e4b-8f2f-10053911533b" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -;[ - { - access_method_id: 'a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d', - created_at: '2025-06-16T16:54:17.946606Z', - display_name: 'PIN Code', - is_card_encoding_required: false, - mode: 'code', - workspace_id: '661025d3-c1d2-403c-83a8-af153aaedfbc', - }, - { - access_method_id: '5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f', - created_at: '2025-06-16T16:54:19.946606Z', - display_name: 'Plastic Card', - is_card_encoding_required: true, - mode: 'card', - workspace_id: '661025d3-c1d2-403c-83a8-af153aaedfbc', - }, - { - access_method_id: 'c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f', - created_at: '2025-06-16T16:54:21.946606Z', - display_name: 'Mobile Key', - instant_key_url: 'https://ik.seam.co/ABCXYZ', - is_card_encoding_required: false, - mode: 'mobile_key', - workspace_id: '661025d3-c1d2-403c-83a8-af153aaedfbc', - }, -] -``` - -```curl cURL -{ - "access_methods": [ - { - "access_method_id": "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - "created_at": "2025-06-16T16:54:17.946606Z", - "display_name": "PIN Code", - "is_card_encoding_required": false, - "mode": "code", - "workspace_id": "661025d3-c1d2-403c-83a8-af153aaedfbc" - }, - { - "access_method_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - "created_at": "2025-06-16T16:54:19.946606Z", - "display_name": "Plastic Card", - "is_card_encoding_required": true, - "mode": "card", - "workspace_id": "661025d3-c1d2-403c-83a8-af153aaedfbc" - }, - { - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "created_at": "2025-06-16T16:54:21.946606Z", - "display_name": "Mobile Key", - "instant_key_url": "https://ik.seam.co/ABCXYZ", - "is_card_encoding_required": false, - "mode": "mobile_key", - "workspace_id": "661025d3-c1d2-403c-83a8-af153aaedfbc" - } - ] -} -``` - -```python Python -[ - AccessMethod( - access_method_id="a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - created_at="2025-06-16T16:54:17.946606Z", - display_name="PIN Code", - is_card_encoding_required=false, - mode="code", - workspace_id="661025d3-c1d2-403c-83a8-af153aaedfbc", - ), - AccessMethod( - access_method_id="5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - created_at="2025-06-16T16:54:19.946606Z", - display_name="Plastic Card", - is_card_encoding_required=true, - mode="card", - workspace_id="661025d3-c1d2-403c-83a8-af153aaedfbc", - ), - AccessMethod( - access_method_id="c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - created_at="2025-06-16T16:54:21.946606Z", - display_name="Mobile Key", - instant_key_url="https://ik.seam.co/ABCXYZ", - is_card_encoding_required=false, - mode="mobile_key", - workspace_id="661025d3-c1d2-403c-83a8-af153aaedfbc", - ), -] -``` - -```ruby Ruby -[ - { - "access_method_id" => "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - "created_at" => "2025-06-16T16:54:17.946606Z", - "display_name" => "PIN Code", - "is_card_encoding_required" => false, - "mode" => "code", - "workspace_id" => "661025d3-c1d2-403c-83a8-af153aaedfbc", - }, - { - "access_method_id" => "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - "created_at" => "2025-06-16T16:54:19.946606Z", - "display_name" => "Plastic Card", - "is_card_encoding_required" => true, - "mode" => "card", - "workspace_id" => "661025d3-c1d2-403c-83a8-af153aaedfbc", - }, - { - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "created_at" => "2025-06-16T16:54:21.946606Z", - "display_name" => "Mobile Key", - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - "is_card_encoding_required" => false, - "mode" => "mobile_key", - "workspace_id" => "661025d3-c1d2-403c-83a8-af153aaedfbc", - }, -] -``` - -```php PHP -[ - [ - "access_method_id" => "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - "created_at" => "2025-06-16T16:54:17.946606Z", - "display_name" => "PIN Code", - "is_card_encoding_required" => false, - "mode" => "code", - "workspace_id" => "661025d3-c1d2-403c-83a8-af153aaedfbc", - ], - [ - "access_method_id" => "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - "created_at" => "2025-06-16T16:54:19.946606Z", - "display_name" => "Plastic Card", - "is_card_encoding_required" => true, - "mode" => "card", - "workspace_id" => "661025d3-c1d2-403c-83a8-af153aaedfbc", - ], - [ - "access_method_id" => "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - "created_at" => "2025-06-16T16:54:21.946606Z", - "display_name" => "Mobile Key", - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - "is_card_encoding_required" => false, - "mode" => "mobile_key", - "workspace_id" => "661025d3-c1d2-403c-83a8-af153aaedfbc", - ], -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Get an Access Grant - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.get({ - access_grant_id: '704eadf0-a0a2-4715-b0e1-2f002dc1b6e0', -}) -``` - -```curl cURL -curl --include --request POST "https://connect.getseam.com/access_grants/get" \ - --header "Authorization: Bearer $SEAM_API_KEY" \ - --json @- <access_grants->get( - access_grant_id: "704eadf0-a0a2-4715-b0e1-2f002dc1b6e0" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -{ - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"] - }, - { - "display_name": "Mobile Key", - "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": "e3d736c1-540d-4d10-83e5-9a4e135453b4", - "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7" -} -``` - -```curl cURL -{ - "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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"] - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"] - }, - { - "display_name": "Mobile Key", - "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": "e3d736c1-540d-4d10-83e5-9a4e135453b4", - "workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7" - } -} -``` - -```python Python -AccessGrant( - 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", - "mode": "code", - "created_at": "2025-06-16T16:54:17.946606Z", - "created_access_method_ids": ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"], - }, - { - "display_name": "Plastic Card", - "mode": "card", - "created_at": "2025-06-16T16:54:19.946606Z", - "created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - }, - { - "display_name": "Mobile Key", - "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="e3d736c1-540d-4d10-83e5-9a4e135453b4", - workspace_id="750fc0bc-4450-4356-8d9f-18c6a3a6b2c7", -) -``` - -```ruby Ruby -{ - "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", - mode: "code", - created_at: "2025-06-16T16:54:17.946606Z", - created_access_method_ids: ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"], - }, - { - display_name: "Plastic Card", - mode: "card", - created_at: "2025-06-16T16:54:19.946606Z", - created_access_method_ids: ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"], - }, - { - display_name: "Mobile Key", - 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" => "e3d736c1-540d-4d10-83e5-9a4e135453b4", - "workspace_id" => "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7", -} -``` - -```php PHP -[ - "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", - "mode" => "code", - "created_at" => "2025-06-16T16:54:17.946606Z", - "created_access_method_ids" => [ - "a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d", - ], - ], - [ - "display_name" => "Plastic Card", - "mode" => "card", - "created_at" => "2025-06-16T16:54:19.946606Z", - "created_access_method_ids" => [ - "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f", - ], - ], - [ - "display_name" => "Mobile Key", - "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" => "e3d736c1-540d-4d10-83e5-9a4e135453b4", - "workspace_id" => "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7", -]; -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Get an Access Method - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.get({ - access_method_id: '7410aea4-6bed-490c-a602-dd417d9cd075', -}) -``` - -```curl cURL -curl --include --request POST "https://connect.getseam.com/access_methods/get" \ - --header "Authorization: Bearer $SEAM_API_KEY" \ - --json @- <access_methods->get( - access_method_id: "7410aea4-6bed-490c-a602-dd417d9cd075" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -{ - "access_method_id": "7410aea4-6bed-490c-a602-dd417d9cd075", - "created_at": "2025-06-14T16:54:17.946612Z", - "display_name": "My Mobile Key", - "instant_key_url": "https://ik.seam.co/ABCXYZ", - "is_card_encoding_required": false, - "mode": "mobile_key", - "workspace_id": "661025d3-c1d2-403c-83a8-af153aaedfbc" -} -``` - -```curl cURL -{ - "access_method": { - "access_method_id": "7410aea4-6bed-490c-a602-dd417d9cd075", - "created_at": "2025-06-14T16:54:17.946612Z", - "display_name": "My Mobile Key", - "instant_key_url": "https://ik.seam.co/ABCXYZ", - "is_card_encoding_required": false, - "mode": "mobile_key", - "workspace_id": "661025d3-c1d2-403c-83a8-af153aaedfbc" - } -} -``` - -```python Python -AccessMethod( - access_method_id="7410aea4-6bed-490c-a602-dd417d9cd075", - created_at="2025-06-14T16:54:17.946612Z", - display_name="My Mobile Key", - instant_key_url="https://ik.seam.co/ABCXYZ", - is_card_encoding_required=false, - mode="mobile_key", - workspace_id="661025d3-c1d2-403c-83a8-af153aaedfbc", -) -``` - -```ruby Ruby -{ - "access_method_id" => "7410aea4-6bed-490c-a602-dd417d9cd075", - "created_at" => "2025-06-14T16:54:17.946612Z", - "display_name" => "My Mobile Key", - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - "is_card_encoding_required" => false, - "mode" => "mobile_key", - "workspace_id" => "661025d3-c1d2-403c-83a8-af153aaedfbc", -} -``` - -```php PHP -[ - "access_method_id" => "7410aea4-6bed-490c-a602-dd417d9cd075", - "created_at" => "2025-06-14T16:54:17.946612Z", - "display_name" => "My Mobile Key", - "instant_key_url" => "https://ik.seam.co/ABCXYZ", - "is_card_encoding_required" => false, - "mode" => "mobile_key", - "workspace_id" => "661025d3-c1d2-403c-83a8-af153aaedfbc", -]; -``` - -```json C# -// Coming Soon! -``` - - diff --git a/mintlify-docs/use-cases/granting-access/revoking-an-access-method.mdx b/mintlify-docs/use-cases/granting-access/revoking-an-access-method.mdx deleted file mode 100644 index 02454cd9c..000000000 --- a/mintlify-docs/use-cases/granting-access/revoking-an-access-method.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: 'Revoking an Access Method' -description: 'Learn how to revoke an access method so that a user can no longer use it.' ---- - -To revoke an access method, delete it. - -**Code:** - - - -```javascript JavaScript -await seam.accessMethods.delete({ - access_method_id: '3f10d86c-526b-4b85-8788-cc1a74411b71', -}) -``` - -```curl cURL -curl --include --request POST "https://connect.getseam.com/access_methods/delete" \ - --header "Authorization: Bearer $SEAM_API_KEY" \ - --json @- <access_methods->delete( - access_method_id: "3f10d86c-526b-4b85-8788-cc1a74411b71" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -// void -``` - -```curl cURL -{} -``` - -```python Python -None -``` - -```ruby Ruby -nil -``` - -```php PHP - -``` - -```json C# -// Coming Soon! -``` - - diff --git a/mintlify-docs/use-cases/granting-access/updating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/updating-an-access-grant.mdx deleted file mode 100644 index fc558e86d..000000000 --- a/mintlify-docs/use-cases/granting-access/updating-an-access-grant.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: 'Updating an Access Grant' -description: 'Learn how to update the time window for an Access Grant' ---- - -You can update the starting and ending times for an Access Grant. - -Note that you cannot update the access methods, entrances, or spaces associated with an Access Grant. To change these access characteristics, delete the Access Grant and recreate it. - -**Code:** - - - -```javascript JavaScript -await seam.accessGrants.update({ - access_grant_id: '4ec65722-bf38-4b2f-b4c8-f488aa6ba3f1', - starts_at: '2025-06-19T18:01:32.000Z', - ends_at: '2025-06-22T13:24:50.000Z', -}) -``` - -```curl cURL -curl --include --request POST "https://connect.getseam.com/access_grants/update" \ - --header "Authorization: Bearer $SEAM_API_KEY" \ - --json @- <access_grants->update( - access_grant_id: "4ec65722-bf38-4b2f-b4c8-f488aa6ba3f1", - starts_at: "2025-06-19T18:01:32.000Z", - ends_at: "2025-06-22T13:24:50.000Z" -); -``` - -```csharp C# -// Coming Soon! -``` - - - -**Output:** - - - -```javascript JavaScript -// void -``` - -```curl cURL -{} -``` - -```python Python -None -``` - -```ruby Ruby -nil -``` - -```php PHP - -``` - -```json C# -// Coming Soon! -``` - - - ---- - -## Updating Cards - -If you update an Access Grant that includes a card access method, the `access_method.card_encoding_required` event indicates that you must [re-encode the card](../../low-level-apis/access-systems/working-with-card-encoders-and-scanners/creating-and-encoding-card-access-methods) using the same access method. After you re-encode the card, Seam emits an `access_method.reissued` event. - -You can also view the `is_encoding_required`, `is_issued`, and `issued_at` properties of the affected access method. - ---- - -## Updating Mobile Keys - -If you update an Access Grant that includes a mobile key access method, Seam emits an `access_method.reissued` event. - -You can also view the `is_issued` and `issued_at` properties of the affected access method. From bafbca44890535e3cce2f8288365ddb77c68e404 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 00:00:28 -0700 Subject: [PATCH 08/36] fix: update Next Steps links to delivery guide pages Replace link to deleted delivering-access-methods page with links to individual delivery guide pages. Co-Authored-By: Claude Opus 4.6 --- .../granting-access/creating-an-access-grant.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx index df2b615e0..9165463a3 100644 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx +++ b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx @@ -1431,4 +1431,10 @@ Example `access_method.card_encoding_required` event payload: ## Next Steps -Once you've created the Access Grant and the resulting access methods have been issued, deliver the access methods to your user. For details, see [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods). +Once you've created the Access Grant and the resulting access methods have been issued, deliver the access methods to your user. See the delivery guides for each access method mode: + +- [Using PIN Codes](/use-cases/granting-access/using-pin-codes) +- [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) +- [Using Instant Keys](/use-cases/granting-access/using-instant-keys) +- [Using Key Cards](/use-cases/granting-access/using-key-cards) +- [Using Cloud Keys](/use-cases/granting-access/using-cloud-keys) From a292c9eda41f30629aa4128cba8ea48fc55fd2c6 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 00:03:24 -0700 Subject: [PATCH 09/36] fix: restore compact version of creating-an-access-grant The squash commit had an earlier verbose version of this page. Restore the final compact ~235-line version with single code example, 2-step flow, delivery table, and event tracking table. Co-Authored-By: Claude Opus 4.6 --- .../creating-an-access-grant.mdx | 1481 ++--------------- 1 file changed, 138 insertions(+), 1343 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx index 9165463a3..99a98bbd1 100644 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx +++ b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx @@ -1,1440 +1,235 @@ --- -title: 'Creating an Access Grant' -description: 'Learn how to create an Access Grant to define the "who, where, when, and how" for assigning a user access to devices, spaces, or entrances.' +title: "Creating an Access Grant" +description: "Create an Access Grant, check the resulting access methods, and deliver credentials to your user." --- -An Access Grant defines the following characteristics: +An Access Grant is a single API call that defines **who** gets access, **where** they can go, **when** access is valid, and **how** they get in. This guide walks through the full flow from creation to delivery. -- **User identity:** The user to whom you want to grant access. -- **Resources:** The set of devices, spaces, or entrances to which you want to grant the user access. -- **Access schedule:** The starting and ending times for access. -- **Access methods:** The modes of access, such as PIN codes, key cards, mobile keys, and [Instant Keys](/capability-guides/instant-keys/index). - -You specify which resources to grant access to using one of three parameters: - -| Parameter | Use case | Description | -| --- | --- | --- | -| `device_ids` | Standalone smart locks | Pass the IDs of individual devices, such as August, Yale, Schlage, igloohome, or TTLock locks connected through a [Connect Webview](/core-concepts/connect-webviews/index). | -| `space_ids` | Grouped access points | Organize entrances and devices into [spaces](https://docs.seam.co/latest/api/spaces/) first, then grant access to entire spaces. Useful for giving a guest access to everything they need (room door, main entrance, elevator) with one call. | -| `acs_entrance_ids` | Access control system entrances | Pass the IDs of individual ACS entrances. Use this when you want fine-grained control over which entrances to include. | +## Before You Begin -You can also combine these parameters in a single Access Grant. +- A Seam workspace with at least one connected device or access system. You can use a [sandbox workspace](/core-concepts/workspaces/index#sandbox-workspaces) with test devices. +- An [API key](/core-concepts/authentication/api-keys). +- The Seam SDK installed in your language of choice (see [Quick Start](/quickstart)). --- -## Access Grant Creation Process +## Step 1: Create the Access Grant -To create an Access Grant: +Call `/access_grants/create` with four things: -1. [Identify your resources](#identify-your-resources)—the devices, spaces, or entrances to which you want to grant access. -2. [Create a user identity](#create-a-user-identity) for the user to whom you want to grant access. You can also create a new user identity as part of the Access Grant creation. -3. [Create an Access Grant](#create-an-access-grant) specifying the user identity, resources, access schedule, and requested access methods. -4. [Monitor for access method readiness](#monitor-for-access-method-readiness) to know when access methods are issued and ready to deliver. +1. **Who** — a `user_identity_id` for an existing user, or pass `user_identity` to create one inline +2. **Where** — the resources to grant access to +3. **When** — the access schedule (`starts_at` and `ends_at`) +4. **How** — the access method modes to issue (e.g., `code`, `mobile_key`, `card`, `cloud_key`) -If you create an Access Grant that includes a mobile key, the returned Access Grant includes the Instant Key URL for efficient sharing. +### Choosing Resources ---- +You specify _where_ to grant access using one or more of these parameters: -## Before You Begin +| Parameter | Best for | Description | +| ------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `device_ids` | Standalone smart locks | Pass IDs of individual devices like August, Yale, or Schlage locks connected through a [Connect Webview](/core-concepts/connect-webviews/index). | +| `space_ids` | Grouped access points | Grant access to all entrances and devices in one or more [spaces](https://docs.seam.co/latest/api/spaces/). Useful when a guest needs access to a room door, lobby, and elevator in one call. | +| `acs_entrance_ids` | Access control system entrances | Pass IDs of individual ACS entrances for fine-grained control. | -**For standalone smart locks:** [Connect](/core-concepts/connect-webviews/index) the device account to Seam. Confirm that the device supports access codes by checking its `can_program_online_access_codes` capability flag. +You can combine these in a single Access Grant — for example, a standalone smart lock (`device_ids`) plus a set of ACS entrances (`acs_entrance_ids`). - You can try this entire flow in a [sandbox - workspace](/core-concepts/workspaces/index#sandbox-workspaces) using sandbox - devices, such as the August sandbox locks. +If you're using Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, or Vostio, you'll also need to pass a `reservation_key` to coordinate credential override sequencing. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants). -**For access control systems (spaces or entrances):** [Connect](/core-concepts/workspaces/index#connecting-virtual-devices) your access system to Seam. You may also need to set up your access system and confirm that it has the required licenses. For details, see [Setting Up Your Site for Instant Keys](../../capability-guides/instant-keys/setting-up-your-site-for-instant-keys) and the [system integration guide](https://docs.seam.co/latest/device-and-system-integration-guides#access-control-systems) for your access system. - -If you want to use spaces, create them first. For details, see [Spaces](https://docs.seam.co/latest/api/spaces/) and [Create a Space](https://docs.seam.co/latest/api/spaces/create). - ---- +### Example -## Identify Your Resources +The example below creates an Access Grant for a single smart lock with a PIN code. To grant access to multiple doors at once, pass `space_ids` instead of `device_ids`. To target specific ACS entrances, use `acs_entrance_ids`. You can also request multiple modes in one call — for example, `[{"mode": "code"}, {"mode": "mobile_key"}]`. -Depending on your setup, identify the devices, spaces, or entrances to which you want to grant access. + -### List Devices +```python Python +from seam import Seam -List your devices and check the `can_program_online_access_codes` capability flag. +seam = Seam() - - - -**Code:** - -```javascript -const devices = await seam.devices.list() - -const lock = devices.find((device) => device.can_program_online_access_codes) -``` - -**Output:** - -```json -[ - { - "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name": "Front Door", - "can_program_online_access_codes": true, - ... - }, - ... -] -``` - - - - - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/devices/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -**Output:** - -```json -{ - "devices": [ - { - "device_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name": "Front Door", - "can_program_online_access_codes": true, - ... +access_grant = seam.access_grants.create( + user_identity={ + "full_name": "Jane Doe", + "email_address": "jane@example.com", }, - ... - ] -} -``` - - - - - -**Code:** - -```python -devices = seam.devices.list() - -lock = next( - device for device in devices - if device.can_program_online_access_codes + device_ids=["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods=[{"mode": "code"}], + starts_at="2025-07-13T15:00:00.000Z", + ends_at="2025-07-16T11:00:00.000Z", ) ``` -**Output:** - -```python -[ - Device( - device_id="6ba7b811-9dad-11d1-80b4-00c04fd430c8", - display_name="Front Door", - can_program_online_access_codes=true, - ... - ), - ... -] -``` - - - - - -**Code:** - -```ruby -devices = seam.devices.list - -lock = devices.find(&:can_program_online_access_codes) -``` - -**Output:** - -```ruby -[ - { - "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name" => "Front Door", - "can_program_online_access_codes" => true, - ... - }, - ... -] -``` - - - - - -**Code:** - -```php -$devices = $seam->devices->list(); -``` - -**Output:** - -```php -[ - [ - "device_id" => "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - "display_name" => "Front Door", - "can_program_online_access_codes" => true, - ... - ], - ... -]; -``` - - - - - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` - - - - -### List Spaces - -List the spaces and identify the ones to which you want to grant access. - - - - -**Code:** - -```javascript -await seam.spaces.list() -``` - -**Output:** - -```json -[ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -] -``` - - - - - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/spaces/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{}' -``` - -**Output:** - -```json -{ - "spaces": [ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - { - "created_at": "2025-06-16T16:55:31.429200Z", - "display_name": "Common Doors", - "name": "Common Doors", - "space_id": "550e8400-e29b-41d4-a716-446655440000", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... - ], - "ok": true -} -``` - - - - +```javascript JavaScript +import { Seam } from "seam"; -**Code:** +const seam = new Seam(); -```python -seam.spaces.list() -``` - -**Output:** - -```python -[ - { - "created_at": "2025-06-16T16:54:17.946600Z", - "display_name": "Room 101", - "name": "Room 101", - "space_id": "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id": "96bd12f9-6def-4bf4-b517-760417451ae9" +const accessGrant = await seam.accessGrants.create({ + user_identity: { + full_name: "Jane Doe", + email_address: "jane@example.com", }, - ... -] -``` - - - - - -**Code:** - -```ruby -seam.spaces.list() -``` - -**Output:** - -```json -[ - { - "created_at" => "2025-06-16T16:54:17.946600Z", - "display_name" => "Room 101", - "name" => "Room 101", - "space_id" => "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" - }, - ... -] -``` - - - - - -**Code:** - -```php -$seam->spaces->list(); -``` - -**Output:** - -```php -[ - [ - "created_at" => "2025-06-16T16:54:17.946600Z", - "display_name" => "Room 101", - "name" => "Room 101", - "space_id" => "5afeb047-3277-4102-b8c4-99edf05b91d2", - "workspace_id" => "96bd12f9-6def-4bf4-b517-760417451ae9" - ], - ... -]; -``` - - - - - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` - - - - -### List Entrances - -List the entrances in your access system and identify the ones to which you want to grant access. - - - - -**Code:** - -```javascript -await seam.acs.entrances.list({ - acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339', -}) -``` - -**Output:** - -```json -[ - { - "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name": "Main Entrance", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - { - "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc", - "display_name": "Room 101", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - ... -] -``` - - - - - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/acs/entrances/list' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339" -}' -``` - -**Output:** - -```json -{ - "acs_entrances": [ - { - "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name": "Main Entrance", - "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - }, - ... - ] -} -``` - - - - - -**Code:** - -```python -seam.acs.entrances.list( - acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339" -) -``` - -**Output:** - -```python -[ - AcsEntrance( - acs_entrance_id="48ebfb50-c531-43c5-b9ea-409f26dabbd7", - display_name="Main Entrance", - acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ), - ... -] + device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods: [{ mode: "code" }], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z", +}); ``` - - - +```ruby Ruby +require "seam" -**Code:** - -```ruby -seam.acs.entrances.list( - acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" -) -``` +seam = Seam.new() -**Output:** - -```json -[ - { - "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name" => "Main Entrance", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... +access_grant = seam.access_grants.create( + user_identity: { + full_name: "Jane Doe", + email_address: "jane@example.com", }, - ... -] -``` - - - - - -**Code:** - -```php -$seam->acs->entrances->list( - acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339" -); -``` - -**Output:** - -```php -[ - [ - "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "display_name" => "Main Entrance", - "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339", - ... - ], - ... -]; -``` - - - - - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` - - - - ---- - -## Create a User Identity - -You can create a user identity before creating the Access Grant, retrieve an existing one, or create a new user identity as part of the Access Grant creation action. - -To create a user identity, specify the unique `user_identity_key`, `email_address`, or `phone_number` of the user. If you are granting access to an access control system, also include the `acs_system_ids`. - - - - -**Code:** - -```javascript -await seam.userIdentities.create({ - full_name: 'Jane Doe', - email_address: 'jane@example.com', - // Include acs_system_ids if granting access to an ACS: - // acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], -}) -``` - -**Output:** - -```json -{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... -} -``` - - - - - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/user_identities/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "full_name": "Jane Doe", - "email_address": "jane@example.com" -}' -``` - -**Output:** - -```json -{ - "user_identity": { - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name": "Jane Doe", - "email_address": "jane@example.com", - ... - } -} -``` - - - - - -**Code:** - -```python -seam.user_identities.create( - full_name="Jane Doe", - email_address="jane@example.com" - # Include acs_system_ids if granting access to an ACS: - # acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -) -``` - -**Output:** - -```python -UserIdentity( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - full_name="Jane Doe", - email_address="jane@example.com", - ... -) -``` - - - - - -**Code:** - -```ruby -seam.user_identities.create( - full_name: "Jane Doe", - email_address: "jane@example.com", - # Include acs_system_ids if granting access to an ACS: - # acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"], -) -``` - -**Output:** - -```ruby -{ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -} -``` - - - - - -**Code:** - -```php -$seam->user_identities->create( - full_name: "Jane Doe", - email_address: "jane@example.com" - // Include acs_system_ids if granting access to an ACS: - // acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"] -); -``` - -**Output:** - -```php -[ - "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b", - "full_name" => "Jane Doe", - "email_address" => "jane@example.com", - ... -]; -``` - - - - - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` - - - - ---- - -## Create an Access Grant - -Specify the user identity, resources, access schedule, and requested access methods. The examples below show each resource type. - - - You can also create a new user identity inline by passing `user_identity` (with - `full_name` and `email_address`) instead of `user_identity_id`. - - -### Using Device IDs - -Use `device_ids` for standalone smart locks. To grant access to multiple devices, include all the desired device IDs in the array. - - - - -**Code:** - -```javascript -await seam.accessGrants.create({ - user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', - device_ids: ['6ba7b811-9dad-11d1-80b4-00c04fd430c8'], - requested_access_methods: [{ mode: 'code' }], - starts_at: '2025-07-13T15:00:00.000Z', - ends_at: '2025-07-16T11:00:00.000Z', -}) -``` - -**Output:** - -```json -{ - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "PIN Code", - "mode": "code", - "created_access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], - ... - } - ], - ... -} -``` - - - - - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "device_ids": [ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8" - ], - "requested_access_methods": [ - {"mode": "code"} - ], - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z" -}' -``` - -**Output:** - -```json -{ - "access_grant": { - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - ... - } -} -``` - - - - - -**Code:** - -```python -seam.access_grants.create( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - device_ids=[ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8" - ], - requested_access_methods=[ - {"mode": "code"} - ], - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z" -) -``` - - - - - -**Code:** - -```ruby -seam.access_grants.create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - device_ids: %w[6ba7b811-9dad-11d1-80b4-00c04fd430c8], - requested_access_methods: [ - {"mode": "code"} - ], + device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods: [{ "mode": "code" }], starts_at: "2025-07-13T15:00:00.000Z", ends_at: "2025-07-16T11:00:00.000Z" ) ``` - +```php PHP + +$seam = new Seam\SeamClient(); -**Code:** - -```php -$seam->access_grants->create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - device_ids: [ - "6ba7b811-9dad-11d1-80b4-00c04fd430c8", - ], - requested_access_methods: [ - ["mode" => "code"], - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" +$access_grant = $seam->access_grants->create( + user_identity: [ + "full_name" => "Jane Doe", + "email_address" => "jane@example.com", + ], + device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + requested_access_methods: [["mode" => "code"]], + starts_at: "2025-07-13T15:00:00.000Z", + ends_at: "2025-07-16T11:00:00.000Z" ); ``` - - - - -**Code:** - -```csharp -// Coming Soon! +```csharp C# +// Coming soon! ``` -**Output:** - -```json -// Coming Soon! +```java Java +// Coming soon! ``` - - - -### Using Space IDs - -Use `space_ids` to grant access to all entrances in one or more spaces. You can request multiple access method modes, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, include `mobile_key`. - - - - -**Code:** - -```javascript -await seam.accessGrants.create({ - user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', - space_ids: [ - '5afeb047-3277-4102-b8c4-99edf05b91d2', - '550e8400-e29b-41d4-a716-446655440000', - ], - requested_access_methods: [ - { mode: 'code' }, - { mode: 'card' }, - { mode: 'mobile_key' }, - ], - starts_at: '2025-07-13T15:00:00.000Z', - ends_at: '2025-07-16T11:00:00.000Z', -}) -``` - -**Output:** - -```json -{ - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "space_ids": [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods": [ - { - "display_name": "PIN Code", - "mode": "code", - ... - }, - { - "display_name": "Plastic Card", - "mode": "card", - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... -} -``` - - - - - -**Code:** - -```bash +```bash cURL (bash) curl -X 'POST' \ 'https://connect.getseam.com/access_grants/create' \ -H 'accept: application/json' \ -H "Authorization: Bearer ${SEAM_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "space_ids": [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - "requested_access_methods": [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], + "user_identity": { + "full_name": "Jane Doe", + "email_address": "jane@example.com" + }, + "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], + "requested_access_methods": [{"mode": "code"}], "starts_at": "2025-07-13T15:00:00.000Z", "ends_at": "2025-07-16T11:00:00.000Z" -}' + }' ``` -**Output:** + -```json -{ - "access_grant": { - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - ... - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... - } -} -``` - - - - - -**Code:** + +When you request `mobile_key`, Seam also generates an `instant_key_url` on the Access Grant — a shareable link that gives your user mobile access without downloading an app. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys). + -```python -seam.access_grants.create( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - space_ids=[ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - requested_access_methods=[ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z" -) -``` +--- - +## Step 2: Deliver the Access Methods - +After creating the grant, list the access methods to see what was created and check their issuance status. -**Code:** + -```ruby -seam.access_grants.create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - space_ids: %w[5afeb047-3277-4102-b8c4-99edf05b91d2 550e8400-e29b-41d4-a716-446655440000], - requested_access_methods: [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" +```python Python +access_methods = seam.access_methods.list( + access_grant_id=access_grant.access_grant_id ) -``` - - - - -**Code:** - -```php -$seam->access_grants->create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - space_ids: [ - "5afeb047-3277-4102-b8c4-99edf05b91d2", - "550e8400-e29b-41d4-a716-446655440000" - ], - requested_access_methods: [ - ["mode" => "code"], - ["mode" => "card"], - ["mode" => "mobile_key"], - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -); -``` - - - - - -**Code:** - -```csharp -// Coming Soon! +for method in access_methods: + print(f"{method.mode}: is_issued={method.is_issued}") ``` -**Output:** - -```json -// Coming Soon! -``` - - - - -### Using Entrance IDs - -Use `acs_entrance_ids` to grant access to specific ACS entrances. You can request multiple access method modes, such as `code`, `card`, and `mobile_key`. To issue an Instant Key, include `mobile_key`. +```javascript JavaScript +const accessMethods = await seam.accessMethods.list({ + access_grant_id: accessGrant.access_grant_id, +}); - - - -**Code:** - -```javascript -await seam.accessGrants.create({ - user_identity_id: '43947360-cdc8-4db6-8b22-e079416d1d8b', - acs_entrance_ids: [ - '48ebfb50-c531-43c5-b9ea-409f26dabbd7', - 'f74e4879-5991-4e2f-a368-888983dcfbfc', - ], - requested_access_methods: [ - { mode: 'code' }, - { mode: 'card' }, - { mode: 'mobile_key' }, - ], - starts_at: '2025-07-13T15:00:00.000Z', - ends_at: '2025-07-16T11:00:00.000Z', -}) -``` - -**Output:** - -```json -{ - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - "display_name": "My Access Grant", - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z", - "requested_access_methods": [ - { - "display_name": "PIN Code", - "mode": "code", - ... - }, - { - "display_name": "Plastic Card", - "mode": "card", - ... - }, - { - "display_name": "Mobile Key", - "mode": "mobile_key", - ... - } - ], - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... +for (const method of accessMethods) { + console.log(`${method.mode}: is_issued=${method.is_issued}`); } ``` - - - - -**Code:** - -```bash -curl -X 'POST' \ - 'https://connect.getseam.com/access_grants/create' \ - -H 'accept: application/json' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b", - "acs_entrance_ids": [ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc" - ], - "requested_access_methods": [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - "starts_at": "2025-07-13T15:00:00.000Z", - "ends_at": "2025-07-16T11:00:00.000Z" -}' -``` - -**Output:** - -```json -{ - "access_grant": { - "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b", - ... - "instant_key_url": "https://ik.seam.co/ABCXYZ", - ... - } -} -``` - - - - - -**Code:** - -```python -seam.access_grants.create( - user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b", - acs_entrance_ids=[ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc" - ], - requested_access_methods=[ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at="2025-07-13T15:00:00.000Z", - ends_at="2025-07-16T11:00:00.000Z" +```ruby Ruby +access_methods = seam.access_methods.list( + access_grant_id: access_grant.access_grant_id ) -``` - - - - - -**Code:** -```ruby -seam.access_grants.create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc], - requested_access_methods: [ - {"mode": "code"}, - {"mode": "card"}, - {"mode": "mobile_key"} - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" -) +access_methods.each do |method| + puts "#{method.mode}: is_issued=#{method.is_issued}" +end ``` - - - - -**Code:** - -```php -$seam->access_grants->create( - user_identity_id: "43947360-cdc8-4db6-8b22-e079416d1d8b", - acs_entrance_ids: [ - "48ebfb50-c531-43c5-b9ea-409f26dabbd7", - "f74e4879-5991-4e2f-a368-888983dcfbfc", - ], - requested_access_methods: [ - ["mode" => "code"], - ["mode" => "card"], - ["mode" => "mobile_key"], - ], - starts_at: "2025-07-13T15:00:00.000Z", - ends_at: "2025-07-16T11:00:00.000Z" +```php PHP +$access_methods = $seam->access_methods->list( + access_grant_id: $access_grant->access_grant_id ); -``` - - - - -**Code:** - -```csharp -// Coming Soon! +foreach ($access_methods as $method) { + echo $method->mode . ": is_issued=" . $method->is_issued . "\n"; +} ``` -**Output:** - -```json -// Coming Soon! +```csharp C# +// Coming soon! ``` - - - ---- - -## Monitor for Access Method Readiness - -Once you've created an Access Grant, monitor the resulting access methods to know when they are ready to deliver to your user. - -### Poll for Status Changes - -Get the access methods by ID and check the following properties: - -- `is_encoding_required`: If `true`, you must encode the card access method onto a plastic key card. See [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index). -- `is_issued`: When `true`, the access method is ready to be delivered to your user. - - - - -**Code:** - -```javascript -await seam.accessMethods.get({ - access_method_id: 'f47ac10b-58cc-4372-a567-0e02b2c3d479', -}) +```java Java +// Coming soon! ``` -**Output:** - -```json -{ - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name": "PIN Code", - "mode": "code", - "is_issued": true, - "code": "1234", - ... -} -``` - - - - - -**Code:** - -```bash +```bash cURL (bash) curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ + 'https://connect.getseam.com/access_methods/list' \ -H 'accept: application/json' \ -H "Authorization: Bearer ${SEAM_API_KEY}" \ -H 'Content-Type: application/json' \ - -d '{ - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" -}' + -d "{\"access_grant_id\": \"${access_grant_id}\"}" ``` -**Output:** + -```json -{ - "access_method": { - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name": "PIN Code", - "mode": "code", - "is_issued": true, - "code": "1234", - ... - }, - "ok": true -} -``` - - - - +Each access method has an `is_issued` flag. Once it's `true`, the credential is active and ready to deliver. How you deliver depends on the mode: -**Code:** - -```python -seam.access_methods.get( - access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479" -) -``` - -**Output:** - -```python -AccessMethod( - access_method_id="f47ac10b-58cc-4372-a567-0e02b2c3d479", - display_name="PIN Code", - mode="code", - is_issued=true, - code="1234", - ... -) -``` - - - - - -**Code:** - -```ruby -seam.access_methods.get( - access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" -) -``` - -**Output:** - -```ruby -{ - "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name" => "PIN Code", - "mode" => "code", - "is_issued" => true, - "code" => "1234", - ... -} -``` +| Mode | What to do | Guide | +| ------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| `code` | Read the `code` property and share the PIN with your user. | [Using PIN Codes](/use-cases/granting-access/using-pin-codes) | +| `mobile_key` | Initialize the Seam mobile SDK with the `client_session_token`, or send the `instant_key_url`. | [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) / [Instant Keys](/use-cases/granting-access/using-instant-keys) | +| `card` | Encode the credential onto a physical card. `is_issued` becomes `true` after encoding. | [Using Key Cards](/use-cases/granting-access/using-key-cards) | +| `cloud_key` | Call `access_methods.unlock_door` to unlock on behalf of the user. | [Using Cloud Keys](/use-cases/granting-access/using-cloud-keys) | - - - - -**Code:** - -```php -$seam->access_methods->get( - access_method_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" -); -``` - -**Output:** - -```php -[ - "access_method_id" => "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "display_name" => "PIN Code", - "mode" => "code", - "is_issued" => true, - "code" => "1234", - ... -]; -``` - - - - - -**Code:** - -```csharp -// Coming Soon! -``` - -**Output:** - -```json -// Coming Soon! -``` - - - - -### Watch for Lifecycle Events - -You can also watch for the following access method events: - -- `access_method.issued` — An access method is ready to deliver to your user. -- `access_method.card_encoding_required` — A card access method needs to be encoded onto a plastic card. -- `access_method.card_assignment_required` — A card access method requires manual assignment to a physical card before it can be issued. - -Example `access_method.card_encoding_required` event payload: - -```json -{ - "event_id": "22222222-3333-4444-5555-666666666666", - "event_description": "An access method representing a physical card requires encoding.", - "event_type": "access_method.card_encoding_required", - "acs_system_id": "11111111-1111-1111-1111-111111111111", - "access_method_id": "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", - ... -} -``` - ---- + +In a sandbox workspace, automatically-issued access methods are ready almost instantly. On real devices, issuance can take a few moments. + -## Next Steps +### Tracking Issuance with Events -Once you've created the Access Grant and the resulting access methods have been issued, deliver the access methods to your user. See the delivery guides for each access method mode: +Instead of polling `is_issued`, you can listen for [webhook](/developer-tools/webhooks) events: -- [Using PIN Codes](/use-cases/granting-access/using-pin-codes) -- [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) -- [Using Instant Keys](/use-cases/granting-access/using-instant-keys) -- [Using Key Cards](/use-cases/granting-access/using-key-cards) -- [Using Cloud Keys](/use-cases/granting-access/using-cloud-keys) +| Event | Meaning | +| ------------------------------------------ | -------------------------------------------------------- | +| `access_method.issued` | The access method is ready to deliver. | +| `access_method.card_encoding_required` | A card needs to be encoded before it can be delivered. | +| `access_method.card_assignment_required` | A card needs to be assigned to a physical card before it can be issued. | From dcedaa53801f6dac474c2a2636a7d5337d03be27 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 00:06:20 -0700 Subject: [PATCH 10/36] fix: update broken anchor links in granting-access index The compact creating-an-access-grant page no longer has #using-device-ids, #using-space-ids, #using-entrance-ids anchors. Point to #choosing-resources instead. Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 449961f7c..0f33f3c4b 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -107,9 +107,9 @@ Access Grants work across the entire Seam provider lineup: We recommend learning Access Grants in three steps, from the simplest setup to the most advanced: -1. **One device.** Connect a smart lock and create an Access Grant with a single `device_id` and a `code` access method. See [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant#using-device-ids). -2. **Multiple devices and spaces.** Pass several `device_ids` in one call to grant access to a set of locks at once. To manage groups of access points by name—for example, everything a guest in Unit 101 needs—organize them into [spaces](/use-cases/granting-access/creating-an-access-grant#using-space-ids) and grant access by `space_id`. -3. **Access control systems.** Connect an ACS, such as Salto, Visionline, or Brivo, and grant access to entrances with `acs_entrance_ids`. This path can involve additional setup, such as licenses, on-premises connections through Seam Bridge, mobile key configuration, and [reservations](/use-cases/granting-access/reservation-access-grants) for offline-override systems. See [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant#using-entrance-ids). +1. **One device.** Connect a smart lock and create an Access Grant with a single `device_id` and a `code` access method. See [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant). +2. **Multiple devices and spaces.** Pass several `device_ids` in one call to grant access to a set of locks at once. To manage groups of access points by name—for example, everything a guest in Unit 101 needs—organize them into [spaces](/use-cases/granting-access/creating-an-access-grant#choosing-resources) and grant access by `space_id`. +3. **Access control systems.** Connect an ACS, such as Salto, Visionline, or Brivo, and grant access to entrances with `acs_entrance_ids`. This path can involve additional setup, such as licenses, on-premises connections through Seam Bridge, mobile key configuration, and [reservations](/use-cases/granting-access/reservation-access-grants) for offline-override systems. See [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant#choosing-resources). --- From 86270b3c660ca47ad12327ba752b9ec9674f6994 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 00:07:35 -0700 Subject: [PATCH 11/36] feat: simplify granting-access overview page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove redundant characteristics and process tables that duplicate the creating-an-access-grant guide. Fix links to deleted pages. 417 → 164 lines. Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/index.mdx | 289 ++---------------- 1 file changed, 18 insertions(+), 271 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 0f33f3c4b..0b1872cb0 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -4,9 +4,7 @@ sidebarTitle: 'Overview' description: 'Access Grants are the default and recommended way to grant access to any physical space, across smart locks and access control systems.' --- -Use **Access Grants** to grant a person access to a physical space. Access Grants are the default and recommended way to grant access on Seam—for any kind of space (a home, a building, a locker, a parking structure) and irrespective of the locking hardware (standalone smart locks, access control systems, and more). - -With one API call, you tell Seam _who_ should have access, _where_, _when_, and _how_. Seam creates the credential, attaches it to a user identity, encodes the time window, propagates it to every relevant device, and re-materializes it as devices come online, get added to spaces, or change ownership. PIN codes, mobile keys, and plastic cards—all through the same request. +Use **Access Grants** to grant a person access to a physical space. With one API call, you tell Seam _who_ should have access, _where_, _when_, and _how_. Seam creates the credential, propagates it to every relevant device, and re-materializes it as devices come online or change ownership. PIN codes, mobile keys, key cards, and cloud keys — all through the same request. @@ -33,11 +31,7 @@ curl --include --request POST "https://connect.getseam.com/access_grants/create" "email_address": "jane@example.com" }, "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"], - "requested_access_methods": [ - { - "mode": "code" - } - ], + "requested_access_methods": [{"mode": "code"}], "starts_at": "2025-07-13T15:00:00.000Z", "ends_at": "2025-07-16T11:00:00.000Z" } @@ -97,295 +91,48 @@ seam access-grants create --user_identity {"full_name":"Jane Doe","email_address Access Grants work across the entire Seam provider lineup: -- **Standalone smart locks**, such as August, Yale, Schlage, Lockly, TTLock, Tedee, and igloohome devices. Specify the locks directly with `device_ids`. -- **Access control systems (ACS)**, such as Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and Avigilon Alta. Specify entrances with `acs_entrance_ids`. -- **Mixed estates.** Combine `device_ids` and `acs_entrance_ids` in the same Access Grant, or group access points into [spaces](https://docs.seam.co/latest/api/spaces) and grant access to the whole group with `space_ids`. +- **Standalone smart locks** — August, Yale, Schlage, Lockly, TTLock, Tedee, igloohome, and more. Specify locks with `device_ids`. +- **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, Avigilon Alta, and more. Specify entrances with `acs_entrance_ids`. +- **Mixed estates** — Combine `device_ids` and `acs_entrance_ids` in the same grant, or group access points into [spaces](https://docs.seam.co/latest/api/spaces) and use `space_ids`. --- ## Start Simple, Then Scale Up -We recommend learning Access Grants in three steps, from the simplest setup to the most advanced: - 1. **One device.** Connect a smart lock and create an Access Grant with a single `device_id` and a `code` access method. See [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant). -2. **Multiple devices and spaces.** Pass several `device_ids` in one call to grant access to a set of locks at once. To manage groups of access points by name—for example, everything a guest in Unit 101 needs—organize them into [spaces](/use-cases/granting-access/creating-an-access-grant#choosing-resources) and grant access by `space_id`. -3. **Access control systems.** Connect an ACS, such as Salto, Visionline, or Brivo, and grant access to entrances with `acs_entrance_ids`. This path can involve additional setup, such as licenses, on-premises connections through Seam Bridge, mobile key configuration, and [reservations](/use-cases/granting-access/reservation-access-grants) for offline-override systems. See [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant#choosing-resources). - ---- - -## Access Grant Characteristics - -An Access Grant includes the following characteristics: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicCreation ParameterDescription
Who - user_identity_id or user_identity - - The user to whom to grant access. You can either create a user identity - separately and specify the ID to the Access Grant or create a new user - identity as part of the Access Grant creation action. -
Where - device_ids, space_ids, or{' '} - acs_entrance_ids - - The access points to which to grant access. Specify one or more devices - (such as standalone smart locks) by ID, one or more access system - entrances by ID, or both. Alternately, you can define{' '} - spaces that contain - groups of related devices and entrances and then specify one or more - spaces by ID. -
When - starts_at and ends_at - The access schedule.
How - requested_access_methods and mode - - The access methods that you want to grant for the user. In each{' '} - requested_access_method, specify the desired{' '} - mode of access, such as a PIN code, key card, or mobile key - (with an{' '} - Instant Key - ). -
+2. **Multiple devices and spaces.** Pass several `device_ids` in one call, or organize access points into [spaces](/use-cases/granting-access/creating-an-access-grant#choosing-resources) and grant access by `space_id`. +3. **Access control systems.** Connect an ACS and grant access to entrances with `acs_entrance_ids`. This path may involve additional setup — licenses, Seam Bridge connections, mobile key configuration, and [reservations](/use-cases/granting-access/reservation-access-grants) for override-based systems. --- -## Access Grant Process - -The Access Grant process consists of the following steps: +## Reservations for Override-Based Systems - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StepDescription
-
    -
  1. Connect your devices or access system to Seam.
    2. -
- 		- To connect your devices or access system to Seam, we recommend embedding - a{' '} - - Connect Webview - {' '} - in your application. The Connect Webview flow guides the property - manager through each step of the connection process. -
- For standalone smart locks, this is all the setup you need. -
- For on-premises access systems, use Seam Bridge to connect the access - system securely to Seam. For details, see{' '} - - Connect an Access System to Seam - - . -
-
    -
  1. (Access systems only) Set up your site.
    2. -
- 		- If you are granting access to access system entrances, confirm hardware - capabilities and make sure that you have the required licenses. For - example, if you plan to use mobile keys or Instant Keys, your lock - hardware must support Bluetooth Low Energy (BLE) keys. Also, to use - mobile keys with your access system, you may need to purchase licenses - or subscriptions to activate certain software features. These - requirements vary by access system. For details, see{' '} - - Setting Up Your Site for Instant Keys - {' '} - and the{' '} - - system integration guide - {' '} - for your access system. -
-
    -
  1. - (Optional) Set up spaces to organize access points into logical - groups. -
    2. -
- 		- You can use spaces to create groups of devices and entrances for - efficiency. For example, a user staying in Room 101 may need access to - the Room 101 door, the main entrance door, and the nearest elevator. You - could create a space that includes these access points and then use this - space when creating an Access Grant. -
- For details, see{' '} - spaces. -
-
    -
  1. Create a user identity.
    2. -
- 		- User identities represent your users—the people to whom you want to - grant access. You can create a user identity before creating an Access - Grant, or you can create a user identity as part of creating the Access - Grant. -
- See{' '} - - Managing Mobile App User Accounts with User Identities - - . -
-
    -
  1. Create an Access Grant.
    2. -
- 		- When you create an Access Grant, you specify the user identity to whom - you want to grant access, the access schedule, the set of devices, - entrances, or spaces, and one or more access methods that you want to - request. -
- See{' '} - - Creating an Access Grant - - .
- You can poll for access method status changes or watch for Access Grant - and access method lifecycle events that alert you to next steps, such as - how and when to deliver each created access method to your user. -
-
    -
  1. Deliver the access method to the user.
    2. -
- 		-

- Once Seam alerts you that your access methods are ready, deliver them - to your user. Delivery steps depend on the mode of access, such as PIN - code, plastic key card, or mobile key. -

-
    -
  • - If you have created an Access Grant that includes a{' '} - code access method, retrieve the access method to get - the PIN code and share it with your user. -
    • -
  • - If you have created an Access Grant that includes a{' '} - card access method, you may need to encode the card - using the Seam encoders API. -
    • -
  • - If you have created an Access Grant that includes a mobile key, you - can use the Seam mobile SDKs to develop your mobile app that - delivers these mobile keys to your users. -
    • -
  • - Each mobile key also includes an Instant Key URL. To share this - Instant Key with your user, send it through text or email or embed - it in your own app. -
    • -
-

- See{' '} - Delivering Access Methods. -

-
+Some access control systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) use credential override sequencing for guest access. When creating Access Grants for these systems, you need to pass a `reservation_key`. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants). --- -## Which API Should I Use to Grant Access? +## Which API Should I Use? **Use Access Grants.** The lower-level APIs remain available for a small set of specific scenarios: -| Scenario | API to use | +| Scenario | API | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | -| Grant a person access to one or more smart locks | Access Grants (`device_ids`) | +| Grant a person access to smart locks | Access Grants (`device_ids`) | | Grant a person access to ACS entrances | Access Grants (`acs_entrance_ids`) | | Grant a person access to a group of access points | Access Grants + [spaces](https://docs.seam.co/latest/api/spaces) (`space_ids`) | | Issue a mobile key or Instant Key | Access Grants (`mode: "mobile_key"`) | -| Set a PIN with a specific custom code value on a single lock | [Access Codes API](../../low-level-apis/smart-locks/access-codes/index) (low-level) | -| Manage offline or backup PIN code pools on a single lock | [Access Codes API](../../low-level-apis/smart-locks/access-codes/index) (low-level) | -| Directly manage ACS users, credentials, and access groups | [ACS API](../../low-level-apis/access-systems/index) (low-level) | -| Lock or unlock a door remotely | [Smart Locks API](../../low-level-apis/smart-locks/index) (not a granting workflow) | +| Set a specific custom PIN code on a single lock | [Access Codes API](../../low-level-apis/smart-locks/access-codes/index) (low-level) | +| Manage offline or backup PIN code pools | [Access Codes API](../../low-level-apis/smart-locks/access-codes/index) (low-level) | +| Directly manage ACS users, credentials, and access groups | [ACS API](../../low-level-apis/access-systems/index) (low-level) | - The low-level [Access - Codes](../../low-level-apis/smart-locks/access-codes/index) and - [ACS](../../low-level-apis/access-systems/index) granting workflows are - no longer recommended for granting access. For new development, use Access - Grants—they cover the same providers through one consistent, future-proof - interface. + The low-level [Access Codes](../../low-level-apis/smart-locks/access-codes/index) and [ACS](../../low-level-apis/access-systems/index) granting workflows are no longer recommended. For new development, use Access Grants. --- -## Using Reservations - -Some access control systems (such as Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) rely on offline override behavior for guest and resident credentials. - -When issuing Access Grants for these systems, you’ll need to use reservations to ensure credentials override and join correctly. - -👉 [Learn how to use reservations with Access Grants →](/use-cases/granting-access/reservation-access-grants) - ---- - -## Get Started - -To create your first Access Grant, see the [Access Grant Quick Start](/use-cases/granting-access/access-grant-quick-start). Then, learn more in the following topics: +## Next Steps -- [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) -- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) +- [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — step-by-step guide - [Access Grants API Reference](https://docs.seam.co/latest/api/access_grants/) - [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) From 0892a85322dbf7c4b91a3c3e9bb68204a6f5742f Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 00:08:49 -0700 Subject: [PATCH 12/36] feat: rewrite granting-access overview to lead with benefits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Focus on value props: one API across lock types, every access method in one call, automatic lifecycle management. Cut redundant sections. 164 → 120 lines. Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/index.mdx | 115 +++++++++--------- 1 file changed, 56 insertions(+), 59 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 0b1872cb0..497bcf09e 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -1,14 +1,19 @@ --- title: 'Granting Access' sidebarTitle: 'Overview' -description: 'Access Grants are the default and recommended way to grant access to any physical space, across smart locks and access control systems.' +description: 'One API to grant access across smart locks and access control systems — PIN codes, mobile keys, key cards, and cloud keys.' --- -Use **Access Grants** to grant a person access to a physical space. With one API call, you tell Seam _who_ should have access, _where_, _when_, and _how_. Seam creates the credential, propagates it to every relevant device, and re-materializes it as devices come online or change ownership. PIN codes, mobile keys, key cards, and cloud keys — all through the same request. +**Access Grants** are a single API for granting access to any physical space. Whether you're working with standalone smart locks, enterprise access control systems, or both — one call handles it all. - +- **One integration** for smart locks (August, Yale, Schlage, TTLock, igloohome, and more) and access control systems (Salto, ASSA ABLOY Visionline, dormakaba, Brivo, and more). +- **Every access method** — PIN codes, mobile keys, Instant Keys, key cards, and cloud keys — through the same `requested_access_methods` parameter. +- **Automatic lifecycle management** — Seam propagates credentials to devices, re-materializes them as hardware comes online, and cleans up when access expires. -```javascript JavaScript + + + +```javascript await seam.accessGrants.create({ user_identity: { full_name: 'Jane Doe', @@ -21,24 +26,11 @@ await seam.accessGrants.create({ }) ``` -```bash cURL -curl --include --request POST "https://connect.getseam.com/access_grants/create" \ - --header "Authorization: Bearer $SEAM_API_KEY" \ - --json @- < + + -```python Python +```python seam.access_grants.create( user_identity={ "full_name": "Jane Doe", @@ -51,7 +43,11 @@ seam.access_grants.create( ) ``` -```ruby Ruby + + + + +```ruby seam.access_grants.create( user_identity: { full_name: "Jane Doe", @@ -64,7 +60,11 @@ seam.access_grants.create( ) ``` -```php PHP + + + + +```php $seam->access_grants->create( user_identity: [ "full_name" => "Jane Doe", @@ -79,55 +79,52 @@ $seam->access_grants->create( ); ``` -```csharp C# -// Coming Soon! -``` - -```bash Seam CLI -seam access-grants create --user_identity {"full_name":"Jane Doe","email_address":"jane@example.com"} --device_ids ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"] --requested_access_methods [{"mode":"code"}] --starts_at "2025-07-13T15:00:00.000Z" --ends_at "2025-07-16T11:00:00.000Z" -``` - - + -Access Grants work across the entire Seam provider lineup: + -- **Standalone smart locks** — August, Yale, Schlage, Lockly, TTLock, Tedee, igloohome, and more. Specify locks with `device_ids`. -- **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, Avigilon Alta, and more. Specify entrances with `acs_entrance_ids`. -- **Mixed estates** — Combine `device_ids` and `acs_entrance_ids` in the same grant, or group access points into [spaces](https://docs.seam.co/latest/api/spaces) and use `space_ids`. +```csharp +// Coming Soon! +``` ---- + -## Start Simple, Then Scale Up + -1. **One device.** Connect a smart lock and create an Access Grant with a single `device_id` and a `code` access method. See [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant). -2. **Multiple devices and spaces.** Pass several `device_ids` in one call, or organize access points into [spaces](/use-cases/granting-access/creating-an-access-grant#choosing-resources) and grant access by `space_id`. -3. **Access control systems.** Connect an ACS and grant access to entrances with `acs_entrance_ids`. This path may involve additional setup — licenses, Seam Bridge connections, mobile key configuration, and [reservations](/use-cases/granting-access/reservation-access-grants) for override-based systems. +```bash +curl --include --request POST "https://connect.getseam.com/access_grants/create" \ + --header "Authorization: Bearer $SEAM_API_KEY" \ + --json @- < + -## Reservations for Override-Based Systems +You specify _where_ to grant access using `device_ids` (smart locks), `acs_entrance_ids` (ACS entrances), or `space_ids` (groups of access points). You can combine them in a single grant. -Some access control systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) use credential override sequencing for guest access. When creating Access Grants for these systems, you need to pass a `reservation_key`. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants). + +Override-based access systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) require a `reservation_key` for credential sequencing. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants). + --- -## Which API Should I Use? - -**Use Access Grants.** The lower-level APIs remain available for a small set of specific scenarios: +## When to Use Lower-Level APIs -| Scenario | API | -| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | -| Grant a person access to smart locks | Access Grants (`device_ids`) | -| Grant a person access to ACS entrances | Access Grants (`acs_entrance_ids`) | -| Grant a person access to a group of access points | Access Grants + [spaces](https://docs.seam.co/latest/api/spaces) (`space_ids`) | -| Issue a mobile key or Instant Key | Access Grants (`mode: "mobile_key"`) | -| Set a specific custom PIN code on a single lock | [Access Codes API](../../low-level-apis/smart-locks/access-codes/index) (low-level) | -| Manage offline or backup PIN code pools | [Access Codes API](../../low-level-apis/smart-locks/access-codes/index) (low-level) | -| Directly manage ACS users, credentials, and access groups | [ACS API](../../low-level-apis/access-systems/index) (low-level) | +Access Grants cover the vast majority of use cases. The lower-level APIs are only needed for: - - The low-level [Access Codes](../../low-level-apis/smart-locks/access-codes/index) and [ACS](../../low-level-apis/access-systems/index) granting workflows are no longer recommended. For new development, use Access Grants. - +- **Custom PIN codes** — setting a specific code value on a single lock. Use the [Access Codes API](../../low-level-apis/smart-locks/access-codes/index). +- **Direct ACS management** — managing ACS users, credentials, or access groups outside of Access Grants. Use the [ACS API](../../low-level-apis/access-systems/index). --- From fb179d8b1a3b94b9375743612eaa4c8929038930 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 00:09:52 -0700 Subject: [PATCH 13/36] feat: change title to Overview, remove lower-level API section Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 497bcf09e..02e39aea3 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -1,6 +1,5 @@ --- -title: 'Granting Access' -sidebarTitle: 'Overview' +title: 'Overview' description: 'One API to grant access across smart locks and access control systems — PIN codes, mobile keys, key cards, and cloud keys.' --- @@ -119,15 +118,6 @@ Override-based access systems (Dormakaba Ambiance, Dormakaba Community, Visionli --- -## When to Use Lower-Level APIs - -Access Grants cover the vast majority of use cases. The lower-level APIs are only needed for: - -- **Custom PIN codes** — setting a specific code value on a single lock. Use the [Access Codes API](../../low-level-apis/smart-locks/access-codes/index). -- **Direct ACS management** — managing ACS users, credentials, or access groups outside of Access Grants. Use the [ACS API](../../low-level-apis/access-systems/index). - ---- - ## Next Steps - [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — step-by-step guide From 9043d96565869c097c0176e536f891ccf36e057c Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 10:02:59 -0700 Subject: [PATCH 14/36] feat: add access methods comparison table to overview page Adds a section explaining each access method mode (code, mobile_key, card, cloud_key) with a comparison table showing what each is and when to use it. Also notes that mobile_key automatically generates an Instant Key URL. Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/index.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 02e39aea3..33646e256 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -112,6 +112,23 @@ EOF You specify _where_ to grant access using `device_ids` (smart locks), `acs_entrance_ids` (ACS entrances), or `space_ids` (groups of access points). You can combine them in a single grant. +--- + +## Access Methods + +Each Access Grant can issue one or more **access methods** — the credentials your user actually uses to get through a door. Request them via the `requested_access_methods` parameter. + +| Mode | What it is | Best for | +| --- | --- | --- | +| `code` | A PIN code programmed on the lock. | Simple keypad entry — share a code via text, email, or your app. | +| `mobile_key` | A BLE credential delivered through the [Seam mobile SDK](/capability-guides/mobile-access/mobile-device-sdks/index). | Building a custom app with native mobile unlock. | +| `card` | A credential encoded onto a physical plastic card. | Hotels and offices with existing card infrastructure. | +| `cloud_key` | A remote unlock triggered on behalf of a specific user, attributed in the ACS audit trail. | Audit-traced remote access without physical credentials. | + +When you request `mobile_key`, Seam also generates an **Instant Key** — a shareable URL that gives your user mobile access without downloading an app. Useful for quick delivery via text or email. + +You can request multiple modes in one call — for example, a PIN code _and_ a mobile key — and Seam issues all of them under the same Access Grant. + Override-based access systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) require a `reservation_key` for credential sequencing. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants). From 7368a6e62ca97878b357330b6d033a16db8e4ab5 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 10:05:54 -0700 Subject: [PATCH 15/36] feat: simplify cloud_key description in access methods table Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 33646e256..e4cb51b45 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -123,7 +123,7 @@ Each Access Grant can issue one or more **access methods** — the credentials y | `code` | A PIN code programmed on the lock. | Simple keypad entry — share a code via text, email, or your app. | | `mobile_key` | A BLE credential delivered through the [Seam mobile SDK](/capability-guides/mobile-access/mobile-device-sdks/index). | Building a custom app with native mobile unlock. | | `card` | A credential encoded onto a physical plastic card. | Hotels and offices with existing card infrastructure. | -| `cloud_key` | A remote unlock triggered on behalf of a specific user, attributed in the ACS audit trail. | Audit-traced remote access without physical credentials. | +| `cloud_key` | A web pass for unlocking the door, with access logs. | Remote unlock without physical credentials. | When you request `mobile_key`, Seam also generates an **Instant Key** — a shareable URL that gives your user mobile access without downloading an app. Useful for quick delivery via text or email. From 225e8dd50c6c60d4aa2f2fa82571979a85da46f8 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 10:38:54 -0700 Subject: [PATCH 16/36] fix: use "web unlock" instead of "remote unlock" for cloud_key Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index e4cb51b45..33687e97d 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -123,7 +123,7 @@ Each Access Grant can issue one or more **access methods** — the credentials y | `code` | A PIN code programmed on the lock. | Simple keypad entry — share a code via text, email, or your app. | | `mobile_key` | A BLE credential delivered through the [Seam mobile SDK](/capability-guides/mobile-access/mobile-device-sdks/index). | Building a custom app with native mobile unlock. | | `card` | A credential encoded onto a physical plastic card. | Hotels and offices with existing card infrastructure. | -| `cloud_key` | A web pass for unlocking the door, with access logs. | Remote unlock without physical credentials. | +| `cloud_key` | A web pass for unlocking the door, with access logs. | Web unlock without physical credentials. | When you request `mobile_key`, Seam also generates an **Instant Key** — a shareable URL that gives your user mobile access without downloading an app. Useful for quick delivery via text or email. From 235d7b857cab66c111f52a420d8abd4848f834cd Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 10:41:51 -0700 Subject: [PATCH 17/36] feat: refine card and cloud_key descriptions in access methods table Card: mention both encoding fresh and assigning existing cards. Cloud key: clarify it's for building a web app that unlocks for users. Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 33687e97d..9cee5649e 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -122,8 +122,8 @@ Each Access Grant can issue one or more **access methods** — the credentials y | --- | --- | --- | | `code` | A PIN code programmed on the lock. | Simple keypad entry — share a code via text, email, or your app. | | `mobile_key` | A BLE credential delivered through the [Seam mobile SDK](/capability-guides/mobile-access/mobile-device-sdks/index). | Building a custom app with native mobile unlock. | -| `card` | A credential encoded onto a physical plastic card. | Hotels and offices with existing card infrastructure. | -| `cloud_key` | A web pass for unlocking the door, with access logs. | Web unlock without physical credentials. | +| `card` | A credential on a physical plastic card — either encoded fresh or assigned from an existing card. | Hotels and offices with existing card infrastructure. | +| `cloud_key` | A web pass for unlocking the door, with access logs. | Building a web app that unlocks doors for users. | When you request `mobile_key`, Seam also generates an **Instant Key** — a shareable URL that gives your user mobile access without downloading an app. Useful for quick delivery via text or email. From 13996433b41bdf4518b13c2d957632679ec9cc6f Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 11:03:52 -0700 Subject: [PATCH 18/36] feat: update card and cloud_key descriptions in creating-an-access-grant Card: mention both encoding fresh and assigning existing cards. Cloud key: clarify it unlocks from your web app. Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/creating-an-access-grant.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx index 99a98bbd1..e9878303e 100644 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx +++ b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx @@ -217,8 +217,8 @@ Each access method has an `is_issued` flag. Once it's `true`, the credential is | ------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `code` | Read the `code` property and share the PIN with your user. | [Using PIN Codes](/use-cases/granting-access/using-pin-codes) | | `mobile_key` | Initialize the Seam mobile SDK with the `client_session_token`, or send the `instant_key_url`. | [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) / [Instant Keys](/use-cases/granting-access/using-instant-keys) | -| `card` | Encode the credential onto a physical card. `is_issued` becomes `true` after encoding. | [Using Key Cards](/use-cases/granting-access/using-key-cards) | -| `cloud_key` | Call `access_methods.unlock_door` to unlock on behalf of the user. | [Using Cloud Keys](/use-cases/granting-access/using-cloud-keys) | +| `card` | Encode a fresh card or assign an existing card. `is_issued` becomes `true` after encoding or assignment. | [Using Key Cards](/use-cases/granting-access/using-key-cards) | +| `cloud_key` | Call `access_methods.unlock_door` from your web app to unlock on behalf of the user. | [Using Cloud Keys](/use-cases/granting-access/using-cloud-keys) | In a sandbox workspace, automatically-issued access methods are ready almost instantly. On real devices, issuance can take a few moments. From 2428a2a03184cfba66b1d4745e92d5f62dcaf437 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 11:14:28 -0700 Subject: [PATCH 19/36] fix: cloud_key is an API endpoint, not a web pass Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 9cee5649e..528e0aa28 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -123,7 +123,7 @@ Each Access Grant can issue one or more **access methods** — the credentials y | `code` | A PIN code programmed on the lock. | Simple keypad entry — share a code via text, email, or your app. | | `mobile_key` | A BLE credential delivered through the [Seam mobile SDK](/capability-guides/mobile-access/mobile-device-sdks/index). | Building a custom app with native mobile unlock. | | `card` | A credential on a physical plastic card — either encoded fresh or assigned from an existing card. | Hotels and offices with existing card infrastructure. | -| `cloud_key` | A web pass for unlocking the door, with access logs. | Building a web app that unlocks doors for users. | +| `cloud_key` | An API endpoint for unlocking the door on behalf of a user, with access logs. | Building a web app that unlocks doors for users. | When you request `mobile_key`, Seam also generates an **Instant Key** — a shareable URL that gives your user mobile access without downloading an app. Useful for quick delivery via text or email. From 145bc5a4e4f024e03df95d2bfa8ae8b0cfb2b096 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 11:16:07 -0700 Subject: [PATCH 20/36] feat: move reservation callout to its own section on overview page The override-based access systems note is about grant creation, not access methods. Give it its own section below the Access Methods table. Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 528e0aa28..7ba31c17c 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -129,9 +129,11 @@ When you request `mobile_key`, Seam also generates an **Instant Key** — a shar You can request multiple modes in one call — for example, a PIN code _and_ a mobile key — and Seam issues all of them under the same Access Grant. - -Override-based access systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) require a `reservation_key` for credential sequencing. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants). - +--- + +## Override-Based Access Systems + +Some access systems — Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio — use override-based credential sequencing. These systems require a `reservation_key` when creating an Access Grant so Seam can coordinate credential ordering. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants). --- From 456e3d9b9b23f7b3c4e956d940ac3b9f84a84659 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 11:19:09 -0700 Subject: [PATCH 21/36] feat: expand reservation_key section with both use cases Explain that override-based systems require it for credential sequencing, while other systems use it to reuse the same PIN across multiple Access Grants. Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 7ba31c17c..af891a22c 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -131,9 +131,14 @@ You can request multiple modes in one call — for example, a PIN code _and_ a m --- -## Override-Based Access Systems +## Reservation Keys -Some access systems — Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio — use override-based credential sequencing. These systems require a `reservation_key` when creating an Access Grant so Seam can coordinate credential ordering. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants). +A `reservation_key` is an optional string you can pass when creating an Access Grant. It serves two purposes depending on the system: + +- **Override-based access systems** (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) — these systems **require** a `reservation_key` so Seam can coordinate credential override sequencing across grants. Without it, credentials can conflict. +- **All other systems** — if you pass the same `reservation_key` across multiple Access Grants, Seam reuses the same PIN code for all of them. This is useful when a guest has multiple reservations and you want them to keep the same code. + +See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants) for the full guide. --- From 714980a8b10ff561b8d1411121b115df7fa82d1e Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 11:35:48 -0700 Subject: [PATCH 22/36] feat: note that same user_identity_id reuses access methods across grants Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/creating-an-access-grant.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx index e9878303e..6b5e549db 100644 --- a/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx +++ b/mintlify-docs/use-cases/granting-access/creating-an-access-grant.mdx @@ -38,6 +38,10 @@ You can combine these in a single Access Grant — for example, a standalone sma If you're using Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, or Vostio, you'll also need to pass a `reservation_key` to coordinate credential override sequencing. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants). + +If you create multiple Access Grants for the same `user_identity_id`, Seam tries to reuse the same access methods across grants — for example, assigning the same PIN code so the user doesn't have to learn a new one for each reservation. + + ### Example The example below creates an Access Grant for a single smart lock with a PIN code. To grant access to multiple doors at once, pass `space_ids` instead of `device_ids`. To target specific ACS entrances, use `acs_entrance_ids`. You can also request multiple modes in one call — for example, `[{"mode": "code"}, {"mode": "mobile_key"}]`. From ba0afb96f2bcb3f0ff3b3a70076b3ff33cc6e6af Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 12:11:32 -0700 Subject: [PATCH 23/36] fix: remove incorrect reservation_key bullet for non-override systems Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index af891a22c..28a6db2db 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -133,10 +133,7 @@ You can request multiple modes in one call — for example, a PIN code _and_ a m ## Reservation Keys -A `reservation_key` is an optional string you can pass when creating an Access Grant. It serves two purposes depending on the system: - -- **Override-based access systems** (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) — these systems **require** a `reservation_key` so Seam can coordinate credential override sequencing across grants. Without it, credentials can conflict. -- **All other systems** — if you pass the same `reservation_key` across multiple Access Grants, Seam reuses the same PIN code for all of them. This is useful when a guest has multiple reservations and you want them to keep the same code. +Override-based access systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) **require** a `reservation_key` when creating an Access Grant so Seam can coordinate credential override sequencing across grants. Without it, credentials can conflict. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants) for the full guide. From 6a155adeef3bef2db59ce8d601a04232f74b5cfe Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 12:12:44 -0700 Subject: [PATCH 24/36] feat: rename reservation section to "Special Cases for Hotel Access Systems" Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index 28a6db2db..e143c2cee 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -131,9 +131,9 @@ You can request multiple modes in one call — for example, a PIN code _and_ a m --- -## Reservation Keys +## Special Cases for Hotel Access Systems -Override-based access systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) **require** a `reservation_key` when creating an Access Grant so Seam can coordinate credential override sequencing across grants. Without it, credentials can conflict. +Some hotel access systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) **require** a `reservation_key` when creating an Access Grant so Seam can coordinate credential sequencing across grants. Without it, credentials can conflict. See [Reservation Access Grants](/use-cases/granting-access/reservation-access-grants) for the full guide. From 09ee181edbb038901244579090dfabd7588a3513 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 12:13:28 -0700 Subject: [PATCH 25/36] feat: rename section to "Hotel and Offline Lock Systems" Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mintlify-docs/use-cases/granting-access/index.mdx b/mintlify-docs/use-cases/granting-access/index.mdx index e143c2cee..87b2d9f50 100644 --- a/mintlify-docs/use-cases/granting-access/index.mdx +++ b/mintlify-docs/use-cases/granting-access/index.mdx @@ -131,7 +131,7 @@ You can request multiple modes in one call — for example, a PIN code _and_ a m --- -## Special Cases for Hotel Access Systems +## Hotel and Offline Lock Systems Some hotel access systems (Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, and Vostio) **require** a `reservation_key` when creating an Access Grant so Seam can coordinate credential sequencing across grants. Without it, credentials can conflict. From 142c644832bb02f9ac00ae7dc4bf1426100841b7 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 12:50:27 -0700 Subject: [PATCH 26/36] feat: add get_related section to all delivery pages Each "Using ..." page now shows how to call /access_methods/get_related to list which devices and entrances an access method covers. Co-Authored-By: Claude Opus 4.6 --- .../granting-access/using-cloud-keys.mdx | 36 +++++++++++++++++- .../granting-access/using-instant-keys.mdx | 37 ++++++++++++++++++- .../granting-access/using-key-cards.mdx | 35 +++++++++++++++++- .../granting-access/using-mobile-keys.mdx | 37 ++++++++++++++++++- .../granting-access/using-pin-codes.mdx | 37 ++++++++++++++++++- 5 files changed, 177 insertions(+), 5 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx index 919e71509..fc96f14e9 100644 --- a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx @@ -288,7 +288,41 @@ curl -X 'POST' \ The unlock event appears in the ACS audit trail attributed to the specific user identity, not as a generic system action. +## Listing Related Entrances + +To see which entrances a cloud key can unlock, call `/access_methods/get_related`. + + + +```javascript JavaScript +const related = await seam.accessMethods.getRelated({ + access_method_ids: [accessMethod.access_method_id], +}) + +console.log(related.acs_entrances) // entrances this cloud key can unlock +``` + +```python Python +related = seam.access_methods.get_related( + access_method_ids=[access_method.access_method_id] +) + +print(related.acs_entrances) # entrances this cloud key can unlock +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get_related' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_ids": ["99887766-5544-3322-1100-aabbccddeeff"] +}' +``` + + + ## Next Steps -- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) — Learn how to deliver all access method types to your users. - [Access Grants](/use-cases/granting-access/index) — Learn more about creating and managing Access Grants. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. diff --git a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx index d3b36d46b..27a4f99c3 100644 --- a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx @@ -177,9 +177,44 @@ When your user taps the link on their phone, the Instant Key opens as an iOS App same URL. +## Listing Related Devices and Entrances + +To see which devices or entrances an Instant Key gives access to, call `/access_methods/get_related` with the underlying mobile key's access method ID. + + + +```javascript JavaScript +const related = await seam.accessMethods.getRelated({ + access_method_ids: [accessMethod.access_method_id], +}) + +console.log(related.devices) // smart locks this Instant Key unlocks +console.log(related.acs_entrances) // ACS entrances this Instant Key unlocks +``` + +```python Python +related = seam.access_methods.get_related( + access_method_ids=[access_method.access_method_id] +) + +print(related.devices) # smart locks this Instant Key unlocks +print(related.acs_entrances) # ACS entrances this Instant Key unlocks +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get_related' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"] +}' +``` + + + ## Next Steps - [Instant Keys](/capability-guides/instant-keys/index) — Deep dive into how Instant Keys work, site setup, and advanced delivery options. - [Delivering Instant Keys](/capability-guides/instant-keys/delivering-instant-keys) — Detailed guide for sharing Instant Keys with your users. - [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) — Build a native mobile app experience with the Seam mobile SDKs. -- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) — Learn how to deliver all access method types to your users. diff --git a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx index eb4817dd6..1a8b749f2 100644 --- a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx +++ b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx @@ -357,9 +357,42 @@ If `is_encoding_required` is `false`, the ACS assigns the credential to a card a In this case, once `is_issued` is `true`, the card is ready. Hand the assigned card to your user. +## Listing Related Entrances + +To see which entrances a key card gives access to, call `/access_methods/get_related`. + + + +```javascript JavaScript +const related = await seam.accessMethods.getRelated({ + access_method_ids: [accessMethod.access_method_id], +}) + +console.log(related.acs_entrances) // entrances this card unlocks +``` + +```python Python +related = seam.access_methods.get_related( + access_method_ids=[access_method.access_method_id] +) + +print(related.acs_entrances) # entrances this card unlocks +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get_related' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"] +}' +``` + + + ## Next Steps - [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index) — Complete guide to encoding and scanning cards. -- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) — Learn how to deliver all access method types to your users. - [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — Learn more about specifying devices, entrances, and spaces. - [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. diff --git a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx index c990bcb25..5ad51565e 100644 --- a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx @@ -300,9 +300,44 @@ Use the `client_session_id` to look up the client session token, then pass it to required. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys). +## Listing Related Devices and Entrances + +To see which devices or entrances a mobile key gives access to, call `/access_methods/get_related`. + + + +```javascript JavaScript +const related = await seam.accessMethods.getRelated({ + access_method_ids: [accessMethod.access_method_id], +}) + +console.log(related.devices) // smart locks this mobile key unlocks +console.log(related.acs_entrances) // ACS entrances this mobile key unlocks +``` + +```python Python +related = seam.access_methods.get_related( + access_method_ids=[access_method.access_method_id] +) + +print(related.devices) # smart locks this mobile key unlocks +print(related.acs_entrances) # ACS entrances this mobile key unlocks +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get_related' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"] +}' +``` + + + ## Next Steps - [Mobile Access](/capability-guides/mobile-access/index) — Complete guide to building a mobile app with the Seam mobile SDKs. - [Using Instant Keys](/use-cases/granting-access/using-instant-keys) — Share the Instant Key URL included with every mobile key. -- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) — Learn how to deliver all access method types to your users. - [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. diff --git a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx index 4916bf024..16ef79129 100644 --- a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx +++ b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx @@ -350,8 +350,43 @@ curl -X 'POST' \ } ``` +## Listing Related Devices and Entrances + +To see which devices or entrances a PIN code access method covers, call `/access_methods/get_related`. This returns the devices, ACS entrances, spaces, and other resources associated with the access method. + + + +```javascript JavaScript +const related = await seam.accessMethods.getRelated({ + access_method_ids: [accessMethod.access_method_id], +}) + +console.log(related.devices) // devices this PIN code is programmed on +console.log(related.acs_entrances) // ACS entrances this PIN code unlocks +``` + +```python Python +related = seam.access_methods.get_related( + access_method_ids=[access_method.access_method_id] +) + +print(related.devices) # devices this PIN code is programmed on +print(related.acs_entrances) # ACS entrances this PIN code unlocks +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get_related' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"] +}' +``` + + + ## Next Steps -- [Delivering Access Methods](/use-cases/granting-access/delivering-access-methods) — Learn how to deliver all access method types to your users. - [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — Learn more about specifying devices, entrances, and spaces. - [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. From 262e3e214a05eaf874e97dcb28236c892de673c0 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 12:51:56 -0700 Subject: [PATCH 27/36] fix: remove duplicate redirect sources in docs.json Old redirects pointed to deleted pages; our new redirects point to the restructured pages. Mintlify requires each source path to be unique. Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/docs.json | 24 ------------------------ 1 file changed, 24 deletions(-) diff --git a/mintlify-docs/docs.json b/mintlify-docs/docs.json index 3b117c6bf..461f9d4bc 100644 --- a/mintlify-docs/docs.json +++ b/mintlify-docs/docs.json @@ -1649,10 +1649,6 @@ "source": "/capability-guides/access-grants", "destination": "/use-cases/granting-access" }, - { - "source": "/capability-guides/access-grants/access-grant-quick-start", - "destination": "/use-cases/granting-access/access-grant-quick-start" - }, { "source": "/capability-guides/access-grants/creating-an-access-grant-using-entrances", "destination": "/use-cases/granting-access/creating-an-access-grant-using-entrances" @@ -1661,30 +1657,10 @@ "source": "/capability-guides/access-grants/creating-an-access-grant-using-spaces", "destination": "/use-cases/granting-access/creating-an-access-grant-using-spaces" }, - { - "source": "/capability-guides/access-grants/deleting-an-access-grant", - "destination": "/use-cases/granting-access/deleting-an-access-grant" - }, - { - "source": "/capability-guides/access-grants/delivering-access-methods", - "destination": "/use-cases/granting-access/delivering-access-methods" - }, { "source": "/capability-guides/access-grants/reservation-access-grants", "destination": "/use-cases/granting-access/reservation-access-grants" }, - { - "source": "/capability-guides/access-grants/retrieving-access-grants-and-access-methods", - "destination": "/use-cases/granting-access/retrieving-access-grants-and-access-methods" - }, - { - "source": "/capability-guides/access-grants/revoking-an-access-method", - "destination": "/use-cases/granting-access/revoking-an-access-method" - }, - { - "source": "/capability-guides/access-grants/updating-an-access-grant", - "destination": "/use-cases/granting-access/updating-an-access-grant" - }, { "source": "/capability-guides/access-systems", "destination": "/low-level-apis/access-systems" From e3289cf6f5b31cc7addf816b9784f80316182958 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 12:53:35 -0700 Subject: [PATCH 28/36] fix: mobile keys and instant keys only relate to ACS entrances, not devices Co-Authored-By: Claude Opus 4.6 --- .../use-cases/granting-access/using-instant-keys.mdx | 6 ++---- .../use-cases/granting-access/using-mobile-keys.mdx | 6 ++---- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx index 27a4f99c3..78958b28c 100644 --- a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx @@ -177,9 +177,9 @@ When your user taps the link on their phone, the Instant Key opens as an iOS App same URL. -## Listing Related Devices and Entrances +## Listing Related Entrances -To see which devices or entrances an Instant Key gives access to, call `/access_methods/get_related` with the underlying mobile key's access method ID. +To see which entrances an Instant Key gives access to, call `/access_methods/get_related` with the underlying mobile key's access method ID. @@ -188,7 +188,6 @@ const related = await seam.accessMethods.getRelated({ access_method_ids: [accessMethod.access_method_id], }) -console.log(related.devices) // smart locks this Instant Key unlocks console.log(related.acs_entrances) // ACS entrances this Instant Key unlocks ``` @@ -197,7 +196,6 @@ related = seam.access_methods.get_related( access_method_ids=[access_method.access_method_id] ) -print(related.devices) # smart locks this Instant Key unlocks print(related.acs_entrances) # ACS entrances this Instant Key unlocks ``` diff --git a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx index 5ad51565e..4224240cf 100644 --- a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx @@ -300,9 +300,9 @@ Use the `client_session_id` to look up the client session token, then pass it to required. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys). -## Listing Related Devices and Entrances +## Listing Related Entrances -To see which devices or entrances a mobile key gives access to, call `/access_methods/get_related`. +To see which entrances a mobile key gives access to, call `/access_methods/get_related`. @@ -311,7 +311,6 @@ const related = await seam.accessMethods.getRelated({ access_method_ids: [accessMethod.access_method_id], }) -console.log(related.devices) // smart locks this mobile key unlocks console.log(related.acs_entrances) // ACS entrances this mobile key unlocks ``` @@ -320,7 +319,6 @@ related = seam.access_methods.get_related( access_method_ids=[access_method.access_method_id] ) -print(related.devices) # smart locks this mobile key unlocks print(related.acs_entrances) # ACS entrances this mobile key unlocks ``` From 143462078f3874aabcf2deb71164d0a83f169a92 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 12:54:33 -0700 Subject: [PATCH 29/36] feat: make get_related a numbered step and explain why you need it Each delivery page now has a "List the Doors This X Applies To" step that explains an access method can cover multiple doors and shows how to see which ones. Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx | 4 ++-- .../use-cases/granting-access/using-instant-keys.mdx | 4 ++-- mintlify-docs/use-cases/granting-access/using-key-cards.mdx | 4 ++-- mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx | 4 ++-- mintlify-docs/use-cases/granting-access/using-pin-codes.mdx | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx index fc96f14e9..f9f60efee 100644 --- a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx @@ -288,9 +288,9 @@ curl -X 'POST' \ The unlock event appears in the ACS audit trail attributed to the specific user identity, not as a generic system action. -## Listing Related Entrances +## Step 4: List the Doors This Cloud Key Applies To -To see which entrances a cloud key can unlock, call `/access_methods/get_related`. +An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see exactly which doors a cloud key can unlock, call `/access_methods/get_related`. diff --git a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx index 78958b28c..a1869a76d 100644 --- a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx @@ -177,9 +177,9 @@ When your user taps the link on their phone, the Instant Key opens as an iOS App same URL. -## Listing Related Entrances +## Step 3: List the Doors This Instant Key Applies To -To see which entrances an Instant Key gives access to, call `/access_methods/get_related` with the underlying mobile key's access method ID. +An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see exactly which doors an Instant Key unlocks, call `/access_methods/get_related` with the underlying mobile key's access method ID. diff --git a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx index 1a8b749f2..8a1c0e39d 100644 --- a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx +++ b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx @@ -357,9 +357,9 @@ If `is_encoding_required` is `false`, the ACS assigns the credential to a card a In this case, once `is_issued` is `true`, the card is ready. Hand the assigned card to your user. -## Listing Related Entrances +## Step 4: List the Doors This Key Card Applies To -To see which entrances a key card gives access to, call `/access_methods/get_related`. +An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see exactly which doors a key card unlocks, call `/access_methods/get_related`. diff --git a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx index 4224240cf..b35533c41 100644 --- a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx @@ -300,9 +300,9 @@ Use the `client_session_id` to look up the client session token, then pass it to required. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys). -## Listing Related Entrances +## Step 4: List the Doors This Mobile Key Applies To -To see which entrances a mobile key gives access to, call `/access_methods/get_related`. +An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see exactly which doors a mobile key unlocks, call `/access_methods/get_related`. diff --git a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx index 16ef79129..2972c69cb 100644 --- a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx +++ b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx @@ -350,9 +350,9 @@ curl -X 'POST' \ } ``` -## Listing Related Devices and Entrances +## Step 4: List the Doors This PIN Code Applies To -To see which devices or entrances a PIN code access method covers, call `/access_methods/get_related`. This returns the devices, ACS entrances, spaces, and other resources associated with the access method. +An access method can cover multiple doors — for example, if the Access Grant includes several devices or entrances. To see exactly which doors a PIN code is programmed on, call `/access_methods/get_related`. From 75724a3393ddef830e62cbffb10d8ba09a331b85 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 12:56:34 -0700 Subject: [PATCH 30/36] feat: rename get_related section to informational heading MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "See Which Doors an Access Method Covers" — not a required step. Co-Authored-By: Claude Opus 4.6 --- mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx | 4 ++-- .../use-cases/granting-access/using-instant-keys.mdx | 4 ++-- mintlify-docs/use-cases/granting-access/using-key-cards.mdx | 4 ++-- mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx | 4 ++-- mintlify-docs/use-cases/granting-access/using-pin-codes.mdx | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx index f9f60efee..6e7d175c2 100644 --- a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx @@ -288,9 +288,9 @@ curl -X 'POST' \ The unlock event appears in the ACS audit trail attributed to the specific user identity, not as a generic system action. -## Step 4: List the Doors This Cloud Key Applies To +## See Which Doors an Access Method Covers -An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see exactly which doors a cloud key can unlock, call `/access_methods/get_related`. +An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a cloud key can unlock, call `/access_methods/get_related`. diff --git a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx index a1869a76d..a6485989a 100644 --- a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx @@ -177,9 +177,9 @@ When your user taps the link on their phone, the Instant Key opens as an iOS App same URL. -## Step 3: List the Doors This Instant Key Applies To +## See Which Doors an Access Method Covers -An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see exactly which doors an Instant Key unlocks, call `/access_methods/get_related` with the underlying mobile key's access method ID. +An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors an Instant Key unlocks, call `/access_methods/get_related` with the underlying mobile key's access method ID. diff --git a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx index 8a1c0e39d..ff835b8fc 100644 --- a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx +++ b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx @@ -357,9 +357,9 @@ If `is_encoding_required` is `false`, the ACS assigns the credential to a card a In this case, once `is_issued` is `true`, the card is ready. Hand the assigned card to your user. -## Step 4: List the Doors This Key Card Applies To +## See Which Doors an Access Method Covers -An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see exactly which doors a key card unlocks, call `/access_methods/get_related`. +An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a key card unlocks, call `/access_methods/get_related`. diff --git a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx index b35533c41..4613d094a 100644 --- a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx @@ -300,9 +300,9 @@ Use the `client_session_id` to look up the client session token, then pass it to required. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys). -## Step 4: List the Doors This Mobile Key Applies To +## See Which Doors an Access Method Covers -An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see exactly which doors a mobile key unlocks, call `/access_methods/get_related`. +An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a mobile key unlocks, call `/access_methods/get_related`. diff --git a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx index 2972c69cb..37b46b32e 100644 --- a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx +++ b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx @@ -350,9 +350,9 @@ curl -X 'POST' \ } ``` -## Step 4: List the Doors This PIN Code Applies To +## See Which Doors an Access Method Covers -An access method can cover multiple doors — for example, if the Access Grant includes several devices or entrances. To see exactly which doors a PIN code is programmed on, call `/access_methods/get_related`. +An access method can cover multiple doors — for example, if the Access Grant includes several devices or entrances. To see which doors a PIN code is programmed on, call `/access_methods/get_related`. From ff75e42fcc8d5decdc31e0b43a29a8f5fd84e275 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 12:59:37 -0700 Subject: [PATCH 31/36] feat: move 'See Which Doors' section before unlock step in cloud keys guide The "See Which Doors an Access Method Covers" section now appears before "Step 3: Unlock the Entrance" since users need to know which doors a cloud key covers before triggering an unlock. Co-Authored-By: Claude Opus 4.6 --- .../granting-access/using-cloud-keys.mdx | 68 +++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx index 6e7d175c2..645044efd 100644 --- a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx @@ -211,6 +211,40 @@ curl -X 'POST' \ } ``` +## See Which Doors an Access Method Covers + +An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a cloud key can unlock, call `/access_methods/get_related`. + + + +```javascript JavaScript +const related = await seam.accessMethods.getRelated({ + access_method_ids: [accessMethod.access_method_id], +}) + +console.log(related.acs_entrances) // entrances this cloud key can unlock +``` + +```python Python +related = seam.access_methods.get_related( + access_method_ids=[access_method.access_method_id] +) + +print(related.acs_entrances) # entrances this cloud key can unlock +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/get_related' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_ids": ["99887766-5544-3322-1100-aabbccddeeff"] +}' +``` + + + ## Step 3: Unlock the Entrance Once the access grant is active, unlock the entrance on behalf of the user by calling `/access_methods/unlock_door` with the cloud key `access_method_id` and the `acs_entrance_id`. The endpoint resolves the credential internally and attributes the unlock to the user identity in the ACS audit trail. @@ -288,40 +322,6 @@ curl -X 'POST' \ The unlock event appears in the ACS audit trail attributed to the specific user identity, not as a generic system action. -## See Which Doors an Access Method Covers - -An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a cloud key can unlock, call `/access_methods/get_related`. - - - -```javascript JavaScript -const related = await seam.accessMethods.getRelated({ - access_method_ids: [accessMethod.access_method_id], -}) - -console.log(related.acs_entrances) // entrances this cloud key can unlock -``` - -```python Python -related = seam.access_methods.get_related( - access_method_ids=[access_method.access_method_id] -) - -print(related.acs_entrances) # entrances this cloud key can unlock -``` - -```bash cURL -curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get_related' \ - -H "Authorization: Bearer ${SEAM_API_KEY}" \ - -H 'Content-Type: application/json' \ - -d '{ - "access_method_ids": ["99887766-5544-3322-1100-aabbccddeeff"] -}' -``` - - - ## Next Steps - [Access Grants](/use-cases/granting-access/index) — Learn more about creating and managing Access Grants. From 7728ac71cbb3ac6fae4752df650b7e19fac7e29b Mon Sep 17 00:00:00 2001 From: Dawn Ho Date: Wed, 10 Jun 2026 13:02:49 -0700 Subject: [PATCH 32/36] Updated mintlify pages - Updated mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx - Updated mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx Mintlify-Source: dashboard-editor --- .../reservation-access-grants.mdx | 98 +++---------------- .../granting-access/using-cloud-keys.mdx | 10 +- 2 files changed, 18 insertions(+), 90 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx b/mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx index f2a37a0e6..5f00ba867 100644 --- a/mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx +++ b/mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx @@ -1,6 +1,6 @@ --- -title: 'Reservation Access Grants' -description: 'Learn how to use reservation_key with Access Grants to handle guest and resident credentials on offline access systems.' +title: "Reservation Access Grants" +description: "Learn how to use reservation_key with Access Grants to handle guest and resident credentials on offline access systems." --- ## Overview @@ -55,7 +55,7 @@ Identify the entrances (or spaces) the user should have access to. If you’re looking to issue a guest or resident credential, use the [Entrances API](https://docs.seam.co/latest/api/acs/entrances/) to confirm which entrances support reservation semantics. -``` +```text const entrances = await seam.acs.entrances.list({ space_id: "room-101" }) const entrances_that_support_reservations = entrances.filter(e => e.can_belong_to_reservation) ``` @@ -63,7 +63,7 @@ const entrances_that_support_reservations = entrances.filter(e => e.can_belong_t - If at least one entrance supports reservations → include a `reservation_key`. - If none do → issue a standard access grant (omit `reservation_key`). -#### **For mixed grants: Reservation-capable + non-capable entrances** +#### **For mixed grants: Reservation-capable \+ non-capable entrances** When a single Access Grant includes a mix of entrances, Seam applies reservation behavior per entrance. @@ -92,7 +92,7 @@ await seam.accessGrants.create({ Pass the `reservation_key` to group related grants and let Seam apply override/joiner behavior consistently. -``` +```text await seam.accessGrants.create({ user_identity_id: "guest-1", acs_entrance_ids: ["room-101-id"], @@ -190,11 +190,11 @@ This allows, for example, giving one guest full access and another guest limited Issuing a **superset** of reservation-capable doors isn’t allowed. If you need to expand the set (e.g., adding a new unit), clear the existing grants first and reissue with the new set. -\ +\ ```tsx // Reservation has room-101 (reservation-capable door) @@ -231,7 +231,7 @@ All access grants within the same `reservation_key` must have **overlapping time This ensures the underlying system treats the credentials as part of the same stay or lease and applies proper joiner behavior. - If the time frames **overlap**, the new grant joins the existing reservation. -- If the time frames **don’t overlap**, the new grant is treated as a separate stay and must use a different reservation_key. +- If the time frames **don’t overlap**, the new grant is treated as a separate stay and must use a different reservation\_key. ```tsx // ✅ Valid: overlapping time frames @@ -401,78 +401,10 @@ await seam.acs.encoders.encode_card({ This section lists common validation and conflict errors you may encounter when creating Access Grants with `reservation_key`, along with what they mean and how to resolve them. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
HTTP CodeError titleWhen it happensHow to fix
400 - reservation_key not supported. - - You passed a reservation_key but none of the targeted - entrances support reservations. - - Remove reservation_key or include at least one - reservation-capable entrance. -
400 - reservation_key required for guest cards. - - The targeted provider requires a reservation for guest credentials - (e.g., Visionline) but none was provided. - - Add a reservation_key when issuing guest credentials for - these entrances. -
409Reservation entrance change requires cleanup. - You tried to issue an access grant with a different door set for an - existing reservation. - - List and delete existing access grants for that{' '} - reservation_key, then reissue with the new door set. -
409Reservation joiner entrance set conflict. - A joiner grant includes a superset of the reservation-capable doors. - - Joiners must use the same or a subset of the reservation-capable doors. - Adjust the door set or clear/reissue. -
409Reservation time frames must overlap. - A new access grant’s time frame doesn’t overlap with existing grants for - the same reservation. - - Either adjust the time frame to overlap or use a new{' '} - reservation_key for the separate stay. -
+| +| +| not supported. | You passed a but none of the targeted entrances support reservations. | Remove or include at least one reservation-capable entrance. | +| required for guest cards. | The targeted provider requires a reservation for guest credentials (e.g., Visionline) but none was provided. | Add a when issuing guest credentials for these entrances. | +| You tried to issue an access grant with a different door set for an existing reservation. | List and delete existing access grants for that{' '} , then reissue with the new door set. List and delete existing access grants for that{' '} , then reissue with the new door set. List and delete existing access grants for that{' '} , then reissue with the new door set. | +| A joiner grant includes a superset of the reservation-capable doors. | Joiners must use the same or a subset of the reservation-capable doors. Adjust the door set or clear/reissue. | +| A new access grant’s time frame doesn’t overlap with existing grants for the same reservation. | Either adjust the time frame to overlap or use a new{' '} for the separate stay. Either adjust the time frame to overlap or use a new{' '} for the separate stay. Either adjust the time frame to overlap or use a new{' '} for the separate stay. | \ No newline at end of file diff --git a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx index 645044efd..15a1e66f6 100644 --- a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx @@ -1,12 +1,8 @@ --- -title: 'Using Cloud Keys' -description: >- - Learn how to use cloud keys to trigger web-based unlocks attributed to - specific user identities in the ACS audit trail. +title: "Using Cloud Keys" +description: "Learn how to use cloud keys to trigger web-based unlocks attributed to specific user identities in the ACS audit trail." --- -# Using Cloud Keys - Cloud keys are a web-based unlock access method. When you use a cloud key, the door unlocks over the internet through the ACS cloud connection. Each unlock is attributed to the specific user identity in the ACS audit trail, rather than being recorded as a generic system action. Cloud keys are ideal for: @@ -325,4 +321,4 @@ The unlock event appears in the ACS audit trail attributed to the specific user ## Next Steps - [Access Grants](/use-cases/granting-access/index) — Learn more about creating and managing Access Grants. -- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. \ No newline at end of file From 16554ba927e466fbf37111ad1d56ae783c0d0f5d Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 13:12:17 -0700 Subject: [PATCH 33/36] feat: use access_methods.list instead of access_methods.get in delivery pages Switch the "Retrieve the PIN Code", "Deliver the Mobile Key", and "Deliver the Key Card" steps to use access_methods.list({ access_grant_id }) instead of access_methods.get() with nested ID lookups. Co-Authored-By: Claude Opus 4.6 --- .../granting-access/using-key-cards.mdx | 52 ++++++++-------- .../granting-access/using-mobile-keys.mdx | 60 ++++++++++--------- .../granting-access/using-pin-codes.mdx | 50 ++++++++-------- 3 files changed, 84 insertions(+), 78 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx index ff835b8fc..97cd12645 100644 --- a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx +++ b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx @@ -198,68 +198,70 @@ curl -X 'POST' \ ## Step 3: Deliver the Key Card -Retrieve the access method and check the `is_encoding_required` property to determine whether you need to encode the card or whether the system assigns it automatically. +List the access methods for the Access Grant and check the `is_encoding_required` property to determine whether you need to encode the card or whether the system assigns it automatically. ```javascript JavaScript -const accessMethod = await seam.accessMethods.get({ - access_method_id: - accessGrant.requested_access_methods[0].created_access_method_ids[0], +const accessMethods = await seam.accessMethods.list({ + access_grant_id: accessGrant.access_grant_id, }) -console.log(accessMethod.is_encoding_required) +const card = accessMethods[0] +console.log(card.is_encoding_required) ``` ```python Python -access_method = seam.access_methods.get( - access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0] +access_methods = seam.access_methods.list( + access_grant_id=access_grant.access_grant_id ) -print(access_method.is_encoding_required) +card = access_methods[0] +print(card.is_encoding_required) ``` ```ruby Ruby -access_method = seam.access_methods.get( - access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0] +access_methods = seam.access_methods.list( + access_grant_id: access_grant.access_grant_id ) -puts access_method.is_encoding_required +card = access_methods[0] +puts card.is_encoding_required ``` ```php PHP -$accessMethod = $seam->access_methods->get( - access_method_id: $accessGrant->requested_access_methods[0]->created_access_method_ids[0] +$accessMethods = $seam->access_methods->list( + access_grant_id: $accessGrant->access_grant_id ); -echo $accessMethod->is_encoding_required; +$card = $accessMethods[0]; +echo $card->is_encoding_required; ``` ```csharp C# -var accessMethod = seam.AccessMethods.Get( - accessMethodId: accessGrant.RequestedAccessMethods[0].CreatedAccessMethodIds[0] +var accessMethods = seam.AccessMethods.List( + accessGrantId: accessGrant.AccessGrantId ); -Console.WriteLine(accessMethod.IsEncodingRequired); +var card = accessMethods[0]; +Console.WriteLine(card.IsEncodingRequired); ``` ```java Java -var accessMethod = seam.accessMethods().get( - AccessMethodsGetRequest.builder() - .accessMethodId( - accessGrant.getRequestedAccessMethods().get(0).getCreatedAccessMethodIds().get(0) - ) +var accessMethods = seam.accessMethods().list( + AccessMethodsListRequest.builder() + .accessGrantId(accessGrant.getAccessGrantId()) .build() ); ``` ```bash cURL curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ + 'https://connect.getseam.com/access_methods/list' \ -H "Authorization: Bearer ${SEAM_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ - "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }' ``` @@ -365,7 +367,7 @@ An access method can cover multiple doors — for example, if the Access Grant i ```javascript JavaScript const related = await seam.accessMethods.getRelated({ - access_method_ids: [accessMethod.access_method_id], + access_method_ids: [card.access_method_id], }) console.log(related.acs_entrances) // entrances this card unlocks diff --git a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx index 4613d094a..f8a5b0631 100644 --- a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx @@ -205,73 +205,75 @@ curl -X 'POST' \ ## Step 3: Deliver the Mobile Key -Once the access method is issued, retrieve it to get the `client_session_id`. Use this value to initialize the Seam mobile SDK on your user's device so they can unlock doors from your app. +Once the access method is issued, list the access methods for the Access Grant to get the `client_session_id`. Use this value to initialize the Seam mobile SDK on your user's device so they can unlock doors from your app. ```javascript JavaScript -const accessMethod = await seam.accessMethods.get({ - access_method_id: - accessGrant.requested_access_methods[0].created_access_method_ids[0], +const accessMethods = await seam.accessMethods.list({ + access_grant_id: accessGrant.access_grant_id, }) -console.log(accessMethod.client_session_id) -console.log(accessMethod.instant_key_url) +const mobileKey = accessMethods[0] +console.log(mobileKey.client_session_id) +console.log(mobileKey.instant_key_url) ``` ```python Python -access_method = seam.access_methods.get( - access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0] +access_methods = seam.access_methods.list( + access_grant_id=access_grant.access_grant_id ) -print(access_method.client_session_id) -print(access_method.instant_key_url) +mobile_key = access_methods[0] +print(mobile_key.client_session_id) +print(mobile_key.instant_key_url) ``` ```ruby Ruby -access_method = seam.access_methods.get( - access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0] +access_methods = seam.access_methods.list( + access_grant_id: access_grant.access_grant_id ) -puts access_method.client_session_id -puts access_method.instant_key_url +mobile_key = access_methods[0] +puts mobile_key.client_session_id +puts mobile_key.instant_key_url ``` ```php PHP -$accessMethod = $seam->access_methods->get( - access_method_id: $accessGrant->requested_access_methods[0]->created_access_method_ids[0] +$accessMethods = $seam->access_methods->list( + access_grant_id: $accessGrant->access_grant_id ); -echo $accessMethod->client_session_id; -echo $accessMethod->instant_key_url; +$mobileKey = $accessMethods[0]; +echo $mobileKey->client_session_id; +echo $mobileKey->instant_key_url; ``` ```csharp C# -var accessMethod = seam.AccessMethods.Get( - accessMethodId: accessGrant.RequestedAccessMethods[0].CreatedAccessMethodIds[0] +var accessMethods = seam.AccessMethods.List( + accessGrantId: accessGrant.AccessGrantId ); -Console.WriteLine(accessMethod.ClientSessionId); -Console.WriteLine(accessMethod.InstantKeyUrl); +var mobileKey = accessMethods[0]; +Console.WriteLine(mobileKey.ClientSessionId); +Console.WriteLine(mobileKey.InstantKeyUrl); ``` ```java Java -var accessMethod = seam.accessMethods().get( - AccessMethodsGetRequest.builder() - .accessMethodId( - accessGrant.getRequestedAccessMethods().get(0).getCreatedAccessMethodIds().get(0) - ) +var accessMethods = seam.accessMethods().list( + AccessMethodsListRequest.builder() + .accessGrantId(accessGrant.getAccessGrantId()) .build() ); ``` ```bash cURL curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ + 'https://connect.getseam.com/access_methods/list' \ -H "Authorization: Bearer ${SEAM_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ - "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" + "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }' ``` diff --git a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx index 37b46b32e..db501837f 100644 --- a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx +++ b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx @@ -269,68 +269,70 @@ curl -X 'POST' \ ## Step 3: Retrieve the PIN Code -Once the access method is issued, retrieve it to get the code. Share the code with your user through text, email, or your application. +Once the access method is issued, list the access methods for the Access Grant to get the code. Share the code with your user through text, email, or your application. ```javascript JavaScript -const accessMethod = await seam.accessMethods.get({ - access_method_id: - accessGrant.requested_access_methods[0].created_access_method_ids[0], +const accessMethods = await seam.accessMethods.list({ + access_grant_id: accessGrant.access_grant_id, }) -console.log(accessMethod.code) // => "1234" +const pinCode = accessMethods[0] +console.log(pinCode.code) // => "1234" ``` ```python Python -access_method = seam.access_methods.get( - access_method_id=access_grant.requested_access_methods[0].created_access_method_ids[0] +access_methods = seam.access_methods.list( + access_grant_id=access_grant.access_grant_id ) -print(access_method.code) # => "1234" +pin_code = access_methods[0] +print(pin_code.code) # => "1234" ``` ```ruby Ruby -access_method = seam.access_methods.get( - access_method_id: access_grant.requested_access_methods[0].created_access_method_ids[0] +access_methods = seam.access_methods.list( + access_grant_id: access_grant.access_grant_id ) -puts access_method.code # => "1234" +pin_code = access_methods[0] +puts pin_code.code # => "1234" ``` ```php PHP -$accessMethod = $seam->access_methods->get( - access_method_id: $accessGrant->requested_access_methods[0]->created_access_method_ids[0] +$accessMethods = $seam->access_methods->list( + access_grant_id: $accessGrant->access_grant_id ); -echo $accessMethod->code; // => "1234" +$pinCode = $accessMethods[0]; +echo $pinCode->code; // => "1234" ``` ```csharp C# -var accessMethod = seam.AccessMethods.Get( - accessMethodId: accessGrant.RequestedAccessMethods[0].CreatedAccessMethodIds[0] +var accessMethods = seam.AccessMethods.List( + accessGrantId: accessGrant.AccessGrantId ); -Console.WriteLine(accessMethod.Code); // => "1234" +var pinCode = accessMethods[0]; +Console.WriteLine(pinCode.Code); // => "1234" ``` ```java Java -var accessMethod = seam.accessMethods().get( - AccessMethodsGetRequest.builder() - .accessMethodId( - accessGrant.getRequestedAccessMethods().get(0).getCreatedAccessMethodIds().get(0) - ) +var accessMethods = seam.accessMethods().list( + AccessMethodsListRequest.builder() + .accessGrantId(accessGrant.getAccessGrantId()) .build() ); ``` ```bash cURL curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/get' \ + 'https://connect.getseam.com/access_methods/list' \ -H "Authorization: Bearer ${SEAM_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ - "access_method_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" + "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }' ``` From e29ff233b64d0035dc5faf36ce6cba42b077996f Mon Sep 17 00:00:00 2001 From: Dawn Ho Date: Wed, 10 Jun 2026 13:32:56 -0700 Subject: [PATCH 34/36] Updated mintlify pages - Updated mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx - Updated mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx - Updated mintlify-docs/use-cases/granting-access/using-pin-codes.mdx - Updated mintlify-docs/use-cases/granting-access/using-instant-keys.mdx - Updated mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx - Updated mintlify-docs/use-cases/granting-access/using-key-cards.mdx Mintlify-Source: dashboard-editor --- .../reservation-access-grants.mdx | 10 +- .../granting-access/using-cloud-keys.mdx | 4 +- .../granting-access/using-instant-keys.mdx | 111 ++++++++++++++++-- .../granting-access/using-key-cards.mdx | 89 ++++++++++++-- .../granting-access/using-mobile-keys.mdx | 31 +++-- .../granting-access/using-pin-codes.mdx | 59 ++++++++-- 6 files changed, 254 insertions(+), 50 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx b/mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx index 5f00ba867..0b023525e 100644 --- a/mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx +++ b/mintlify-docs/use-cases/granting-access/reservation-access-grants.mdx @@ -401,10 +401,10 @@ await seam.acs.encoders.encode_card({ This section lists common validation and conflict errors you may encounter when creating Access Grants with `reservation_key`, along with what they mean and how to resolve them. -| -| +| | | | +| --- | --- | --- | | not supported. | You passed a but none of the targeted entrances support reservations. | Remove or include at least one reservation-capable entrance. | | required for guest cards. | The targeted provider requires a reservation for guest credentials (e.g., Visionline) but none was provided. | Add a when issuing guest credentials for these entrances. | -| You tried to issue an access grant with a different door set for an existing reservation. | List and delete existing access grants for that{' '} , then reissue with the new door set. List and delete existing access grants for that{' '} , then reissue with the new door set. List and delete existing access grants for that{' '} , then reissue with the new door set. | -| A joiner grant includes a superset of the reservation-capable doors. | Joiners must use the same or a subset of the reservation-capable doors. Adjust the door set or clear/reissue. | -| A new access grant’s time frame doesn’t overlap with existing grants for the same reservation. | Either adjust the time frame to overlap or use a new{' '} for the separate stay. Either adjust the time frame to overlap or use a new{' '} for the separate stay. Either adjust the time frame to overlap or use a new{' '} for the separate stay. | \ No newline at end of file +| You tried to issue an access grant with a different door set for an existing reservation. | List and delete existing access grants for that{' '} , then reissue with the new door set. List and delete existing access grants for that{' '} , then reissue with the new door set. List and delete existing access grants for that{' '} , then reissue with the new door set. List and delete existing access grants for that{' '} , then reissue with the new door set. | | +| A joiner grant includes a superset of the reservation-capable doors. | Joiners must use the same or a subset of the reservation-capable doors. Adjust the door set or clear/reissue. | | +| A new access grant’s time frame doesn’t overlap with existing grants for the same reservation. | Either adjust the time frame to overlap or use a new{' '} for the separate stay. Either adjust the time frame to overlap or use a new{' '} for the separate stay. Either adjust the time frame to overlap or use a new{' '} for the separate stay. Either adjust the time frame to overlap or use a new{' '} for the separate stay. | | \ No newline at end of file diff --git a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx index 15a1e66f6..25d4086f5 100644 --- a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx @@ -207,7 +207,7 @@ curl -X 'POST' \ } ``` -## See Which Doors an Access Method Covers +## Step 3: See Which Doors an Access Method Covers An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a cloud key can unlock, call `/access_methods/get_related`. @@ -241,7 +241,7 @@ curl -X 'POST' \ -## Step 3: Unlock the Entrance +## Step 4: Unlock the Entrance Once the access grant is active, unlock the entrance on behalf of the user by calling `/access_methods/unlock_door` with the cloud key `access_method_id` and the `acs_entrance_id`. The endpoint resolves the credential internally and attributes the unlock to the user identity in the ACS audit trail. diff --git a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx index a6485989a..c6f341b47 100644 --- a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx @@ -1,8 +1,6 @@ --- -title: 'Using Instant Keys' -description: >- - Learn how to deliver Instant Keys — shareable unlock links that work without - an app download — through Access Grants. +title: "Using Instant Keys" +description: "Learn how to deliver Instant Keys — shareable unlock links that work without an app download — through Access Grants." --- Instant Keys are the fastest way to give someone mobile access. When you create an Access Grant with a `mobile_key` access method, Seam automatically generates an Instant Key URL. Share this URL with your user through text, email, or your app. When they tap the link, they can unlock the door immediately — no app download required. @@ -15,6 +13,8 @@ Instant Keys are ideal for: - **Backup access** — Provide a fallback unlock method alongside a native mobile key in your app. - **Quick onboarding** — Let users unlock immediately while they set up your full mobile app. +--- + ## Before You Begin To use Instant Keys, you need: @@ -26,10 +26,11 @@ To use Instant Keys, you need: - An entrance that supports mobile keys (`can_unlock_with_mobile_key` is `true`) - Instant Keys are generated automatically when you create a mobile key access - method. You do not need to request them separately. + Instant Keys are generated automatically when you create a mobile key access method. You do not need to request them separately. +--- + ## Step 1: Create an Access Grant with a Mobile Key Create an [Access Grant](/use-cases/granting-access/index) specifying `mobile_key` as the requested access method mode. The response includes an `instant_key_url` on the Access Grant itself — you can share it immediately without waiting for the access method to be issued. @@ -160,8 +161,12 @@ curl -X 'POST' \ } ``` +--- + ## Step 2: Share the Instant Key URL +Once the access method is created, list the access methods for the Access Grant to get the `instant_key_url`. + Deliver the `instant_key_url` to your user. Common delivery methods include: - **Text message (SMS)** — Send the URL directly to your user's phone. @@ -171,13 +176,95 @@ Deliver the `instant_key_url` to your user. Common delivery methods include: When your user taps the link on their phone, the Instant Key opens as an iOS App Clip or Android Instant App. They can unlock the door immediately — no app store download needed. + + +```javascript JavaScript +const accessMethods = await seam.accessMethods.list({ + access_grant_id: accessGrant.access_grant_id, +}) + +const instantKey = accessMethods[0] +console.log(instantKey.instant_key_url) +``` + +```python Python +access_methods = seam.access_methods.list( + access_grant_id=access_grant.access_grant_id +) + +instant_key = access_methods[0] +print(instant_key.instant_key_url) +``` + +```ruby Ruby +access_methods = seam.access_methods.list( + access_grant_id: access_grant.access_grant_id +) + +instant_key = access_methods[0] +puts instant_key.instant_key_url +``` + +```php PHP +$accessMethods = $seam->access_methods->list( + access_grant_id: $accessGrant->access_grant_id +); + +$instantKey = $accessMethods[0]; +echo $instantKey->instant_key_url; +``` + +```csharp C# +var accessMethods = seam.AccessMethods.List( + accessGrantId: accessGrant.AccessGrantId +); + +var instantKey = accessMethods[0]; +Console.WriteLine(instantKey.InstantKeyUrl); +``` + +```java Java +var accessMethods = seam.accessMethods().list( + AccessMethodsListRequest.builder() + .accessGrantId(accessGrant.getAccessGrantId()) + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +}' +``` + + + +**Output:** + +```json +{ + "access_method_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", + "display_name": "Mobile Key", + "mode": "mobile_key", + "is_issued": true, + "issued_at": "2025-06-16T16:55:03.924353Z", + "instant_key_url": "https://ik.seam.co/ABCXYZ", + ... +} +``` + +Use the `client_session_id` to look up the client session token, then pass it to the Seam mobile SDK to initialize your user's mobile app. For the complete mobile SDK integration guide, see [Mobile Access](/capability-guides/mobile-access/index). + - The Instant Key URL is also available on the access method itself as - `instant_key_url`. Both the Access Grant and the access method return the - same URL. -## See Which Doors an Access Method Covers +--- + +## Step 3: See Which Doors an Access Method Covers An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors an Instant Key unlocks, call `/access_methods/get_related` with the underlying mobile key's access method ID. @@ -211,8 +298,10 @@ curl -X 'POST' \ +--- + ## Next Steps - [Instant Keys](/capability-guides/instant-keys/index) — Deep dive into how Instant Keys work, site setup, and advanced delivery options. - [Delivering Instant Keys](/capability-guides/instant-keys/delivering-instant-keys) — Detailed guide for sharing Instant Keys with your users. -- [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) — Build a native mobile app experience with the Seam mobile SDKs. +- [Using Mobile Keys](/use-cases/granting-access/using-mobile-keys) — Build a native mobile app experience with the Seam mobile SDKs. \ No newline at end of file diff --git a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx index 97cd12645..beb4debdc 100644 --- a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx +++ b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx @@ -1,8 +1,6 @@ --- -title: 'Using Key Cards' -description: >- - Learn how to create an Access Grant with a key card access method, then encode - or assign the card to your user. +title: "Using Key Cards" +description: "Learn how to create an Access Grant with a key card access method, then encode or assign the card to your user." --- Key cards are plastic cards that unlock doors when presented to a card reader. When you request a `card` access method in an Access Grant, Seam creates a card credential. Depending on your access control system, you either encode the credential onto a physical card using a card encoder or the system assigns the credential to a pre-registered card automatically. @@ -11,6 +9,8 @@ Key cards work with: - **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and other ACS platforms that support card-based credentials. Specify entrances with `acs_entrance_ids` or use `space_ids`. +--- + ## Before You Begin To use key cards, you need: @@ -21,6 +21,8 @@ To use key cards, you need: - An entrance that supports card access (`can_unlock_with_card` is `true`) - For encoding: a compatible card encoder connected to Seam (see [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index)) +--- + ## Step 1: Verify Entrance Support List the entrances for your ACS and confirm that `can_unlock_with_card` is `true`. @@ -98,6 +100,8 @@ curl -X 'POST' \ +--- + ## Step 2: Create an Access Grant with a Key Card Create an [Access Grant](/use-cases/granting-access/index) specifying `card` as the requested access method mode. @@ -196,6 +200,8 @@ curl -X 'POST' \ +--- + ## Step 3: Deliver the Key Card List the access methods for the Access Grant and check the `is_encoding_required` property to determine whether you need to encode the card or whether the system assigns it automatically. @@ -355,11 +361,74 @@ For the complete card encoding workflow, including listing encoders and scanning ### Assigning Cards -If `is_encoding_required` is `false`, the ACS assigns the credential to a card automatically — no physical encoding step is needed. This is common with systems that use pre-registered or cloud-managed cards. +If `is_assigning_required` is `true`, you can assign an existing credential to the access method by providing the card number. This is common with systems that use pre-registered cards. -In this case, once `is_issued` is `true`, the card is ready. Hand the assigned card to your user. +Use the Seam API to input the `card_number` for the access method: -## See Which Doors an Access Method Covers + + +```javascript JavaScript +const actionAttempt = await seam.accessMethods.assignCard({ + access_method_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', + card_number: 'ABCD1234', +}) +``` + +```python Python +action_attempt = seam.access_methods.assign_card( + access_method_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890", + card_number="ABCD1234", +) +``` + +```ruby Ruby +action_attempt = seam.access_methods.assign_card( + access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + card_number: "ABCD1234" +) +``` + +```php PHP +$actionAttempt = $seam->access_methods->encode( + access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + card_number: "ABCD1234" +); +``` + +```csharp C# +var actionAttempt = seam.AccessMethods.Encode( + accessMethodId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + acsEncoderId: "encoder-001" +); +``` + +```java Java +var actionAttempt = seam.accessMethods().encode( + AccessMethodsEncodeRequest.builder() + .accessMethodId("a1b2c3d4-e5f6-7890-abcd-ef1234567890") + .acsEncoderId("encoder-001") + .build() +); +``` + +```bash cURL +curl -X 'POST' \ + 'https://connect.getseam.com/access_methods/encode' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ + "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "acs_encoder_id": "encoder-001" +}' +``` + + + +Once a card is assigned, the access method's `is_assignment_required` property changes to `false` and `is_issued` changes to `true`. Hand the assigned card to your user. + +--- + +## Step 4: See Which Doors the Key Card Covers An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a key card unlocks, call `/access_methods/get_related`. @@ -367,7 +436,7 @@ An access method can cover multiple doors — for example, if the Access Grant i ```javascript JavaScript const related = await seam.accessMethods.getRelated({ - access_method_ids: [card.access_method_id], + access_method_ids: [accessMethod.access_method_id], }) console.log(related.acs_entrances) // entrances this card unlocks @@ -393,8 +462,10 @@ curl -X 'POST' \ +--- + ## Next Steps - [Working with Card Encoders and Scanners](/low-level-apis/access-systems/working-with-card-encoders-and-scanners/index) — Complete guide to encoding and scanning cards. - [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — Learn more about specifying devices, entrances, and spaces. -- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. \ No newline at end of file diff --git a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx index f8a5b0631..d2b082085 100644 --- a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx @@ -1,8 +1,6 @@ --- -title: 'Using Mobile Keys' -description: >- - Learn how to create an Access Grant with a mobile key access method and - deliver it through your mobile app using the Seam mobile SDKs. +title: "Using Mobile Keys" +description: "Learn how to create an Access Grant with a mobile key access method and deliver it through your mobile app using the Seam mobile SDKs." --- Mobile keys let your users unlock doors by tapping a button in your mobile app. When you request a `mobile_key` access method in an Access Grant, Seam issues a mobile credential that you deliver through your own app using the Seam mobile SDKs. Each mobile key also includes an [Instant Key](/capability-guides/instant-keys/index) URL for immediate access without an app download. @@ -11,6 +9,8 @@ Mobile keys work with: - **Access control systems** — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and other ACS platforms that support BLE-based mobile credentials. Specify entrances with `acs_entrance_ids` or use `space_ids`. +--- + ## Before You Begin To use mobile keys, you need: @@ -22,12 +22,11 @@ To use mobile keys, you need: - An entrance that supports mobile keys (`can_unlock_with_mobile_key` is `true`) - If you plan to build a mobile app that delivers mobile keys, see - [Mobile Access](/capability-guides/mobile-access/index) for the complete - SDK integration guide. If you just want to share a link for instant access, - see [Using Instant Keys](/use-cases/granting-access/using-instant-keys) instead. + If you plan to build a mobile app that delivers mobile keys, see [Mobile Access](/capability-guides/mobile-access/index) for the complete SDK integration guide. If you just want to share a link for instant access, see [Using Instant Keys](/use-cases/granting-access/using-instant-keys) instead. +--- + ## Step 1: Verify Entrance Support List the entrances for your ACS and confirm that `can_unlock_with_mobile_key` is `true`. @@ -105,6 +104,8 @@ curl -X 'POST' \ +--- + ## Step 2: Create an Access Grant with a Mobile Key Create an [Access Grant](/use-cases/granting-access/index) specifying `mobile_key` as the requested access method mode. @@ -203,6 +204,8 @@ curl -X 'POST' \ +--- + ## Step 3: Deliver the Mobile Key Once the access method is issued, list the access methods for the Access Grant to get the `client_session_id`. Use this value to initialize the Seam mobile SDK on your user's device so they can unlock doors from your app. @@ -297,12 +300,12 @@ curl -X 'POST' \ Use the `client_session_id` to look up the client session token, then pass it to the Seam mobile SDK to initialize your user's mobile app. For the complete mobile SDK integration guide, see [Mobile Access](/capability-guides/mobile-access/index). - Every mobile key also includes an `instant_key_url`. You can share this URL - with your user as an alternative or backup access method — no app download - required. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys). + Every mobile key also includes an `instant_key_url`. You can share this URL with your user as an alternative or backup access method — no app download required. See [Using Instant Keys](/use-cases/granting-access/using-instant-keys). -## See Which Doors an Access Method Covers +--- + +## Step 4: See Which Doors the Mobile Key Covers An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a mobile key unlocks, call `/access_methods/get_related`. @@ -336,8 +339,10 @@ curl -X 'POST' \ +--- + ## Next Steps - [Mobile Access](/capability-guides/mobile-access/index) — Complete guide to building a mobile app with the Seam mobile SDKs. - [Using Instant Keys](/use-cases/granting-access/using-instant-keys) — Share the Instant Key URL included with every mobile key. -- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. \ No newline at end of file diff --git a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx index db501837f..b7b7ec3c9 100644 --- a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx +++ b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx @@ -1,8 +1,6 @@ --- -title: 'Using PIN Codes' -description: >- - Learn how to create an Access Grant with a PIN code access method and deliver - the code to your user. +title: "Using PIN Codes" +description: "Learn how to create an Access Grant with a PIN code access method and deliver the code to your user." --- PIN codes are the simplest access method. When you request a `code` access method in an Access Grant, Seam programs a PIN code onto the lock. Your user enters the code on the lock's keypad to unlock the door. @@ -12,6 +10,8 @@ PIN codes work with: - **Standalone smart locks** — August, Yale, Schlage, Lockly, TTLock, Tedee, igloohome, and other connected locks. Specify the locks with `device_ids`. - **Access control systems** — Salto KS, Salto Space, Brivo, dormakaba, and other ACS platforms that support PIN-based credentials. Specify entrances with `acs_entrance_ids` or group access points into spaces and use `space_ids`. +--- + ## Before You Begin To use PIN codes, you need: @@ -21,6 +21,8 @@ To use PIN codes, you need: - For standalone smart locks: confirm that `can_program_online_access_codes` is `true` on the device - For ACS entrances: confirm that `can_unlock_with_code` is `true` on the entrance +--- + ## Step 1: Verify Device or Entrance Support ### Standalone Smart Locks @@ -163,6 +165,8 @@ curl -X 'POST' \ +--- + ## Step 2: Create an Access Grant with a PIN Code Create an [Access Grant](/use-cases/granting-access/index) specifying `code` as the requested access method mode. You can target devices, entrances, or spaces. @@ -262,14 +266,14 @@ curl -X 'POST' \ - In a sandbox workspace, PIN codes are issued almost instantly. On real - devices, issuance can take a few moments. Poll the access method until - `is_issued` is `true` or watch for the `access_method.issued` event. + In a sandbox workspace, PIN codes are issued almost instantly. On real devices, issuance can take a few moments. Poll the access method until `is_issued` is `true` or watch for the `access_method.issued` event. +--- + ## Step 3: Retrieve the PIN Code -Once the access method is issued, list the access methods for the Access Grant to get the code. Share the code with your user through text, email, or your application. +Once the access method is issued, list the access methods for the Access Granlist the access methods for the Access Grant to get the code. Share the code with your user through text, email, or your application. @@ -278,6 +282,11 @@ const accessMethods = await seam.accessMethods.list({ access_grant_id: accessGrant.access_grant_id, }) +const pinCode = accessMethods[0] +console.log(pinCodes = await seam.accessMethods.list({ + access_grant_id: accessGrant.access_grant_id, +}) + const pinCode = accessMethods[0] console.log(pinCode.code) // => "1234" ``` @@ -287,6 +296,11 @@ access_methods = seam.access_methods.list( access_grant_id=access_grant.access_grant_id ) +pin_code = access_methods[0] +print(pin_codes = seam.access_methods.list( + access_grant_id=access_grant.access_grant_id +) + pin_code = access_methods[0] print(pin_code.code) # => "1234" ``` @@ -296,6 +310,11 @@ access_methods = seam.access_methods.list( access_grant_id: access_grant.access_grant_id ) +pin_code = access_methods[0] +puts pin_codes = seam.access_methods.list( + access_grant_id: access_grant.access_grant_id +) + pin_code = access_methods[0] puts pin_code.code # => "1234" ``` @@ -305,6 +324,11 @@ $accessMethods = $seam->access_methods->list( access_grant_id: $accessGrant->access_grant_id ); +$pinCode = $accessMethods[0]; +echo $pinCodes = $seam->access_methods->list( + access_grant_id: $accessGrant->access_grant_id +); + $pinCode = $accessMethods[0]; echo $pinCode->code; // => "1234" ``` @@ -314,12 +338,19 @@ var accessMethods = seam.AccessMethods.List( accessGrantId: accessGrant.AccessGrantId ); +var pinCode = accessMethods[0]; +Console.WriteLine(pinCodes = seam.AccessMethods.List( + accessGrantId: accessGrant.AccessGrantId +); + var pinCode = accessMethods[0]; Console.WriteLine(pinCode.Code); // => "1234" ``` ```java Java var accessMethods = seam.accessMethods().list( + AccessMethodsListRequest.builder() + .accessGrantId(accessGrant.getAccessGrantId()s = seam.accessMethods().list( AccessMethodsListRequest.builder() .accessGrantId(accessGrant.getAccessGrantId()) .build() @@ -332,6 +363,10 @@ curl -X 'POST' \ -H "Authorization: Bearer ${SEAM_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ + "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890list' \ + -H "Authorization: Bearer ${SEAM_API_KEY}" \ + -H 'Content-Type: application/json' \ + -d '{ "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }' ``` @@ -352,7 +387,9 @@ curl -X 'POST' \ } ``` -## See Which Doors an Access Method Covers +--- + +## Step 4: See Which Doors an Access Method Covers An access method can cover multiple doors — for example, if the Access Grant includes several devices or entrances. To see which doors a PIN code is programmed on, call `/access_methods/get_related`. @@ -388,7 +425,9 @@ curl -X 'POST' \ +--- + ## Next Steps - [Creating an Access Grant](/use-cases/granting-access/creating-an-access-grant) — Learn more about specifying devices, entrances, and spaces. -- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. +- [Access Methods API Reference](https://docs.seam.co/latest/api/access_methods/) — See all access method properties and endpoints. \ No newline at end of file From 06cc1717af12df1578f806a57cafaf5f83798f7c Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 13:34:07 -0700 Subject: [PATCH 35/36] fix: correct assignCard code samples in PHP, C#, Java, and cURL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These were incorrectly copy-pasted from the encode section — they called access_methods.encode instead of access_methods.assign_card and passed acs_encoder_id instead of card_number. Co-Authored-By: Claude Opus 4.6 --- .../granting-access/using-key-cards.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx index beb4debdc..3fcae6b33 100644 --- a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx +++ b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx @@ -389,36 +389,36 @@ action_attempt = seam.access_methods.assign_card( ``` ```php PHP -$actionAttempt = $seam->access_methods->encode( +$actionAttempt = $seam->access_methods->assign_card( access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", card_number: "ABCD1234" ); ``` ```csharp C# -var actionAttempt = seam.AccessMethods.Encode( +var actionAttempt = seam.AccessMethods.AssignCard( accessMethodId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - acsEncoderId: "encoder-001" + cardNumber: "ABCD1234" ); ``` ```java Java -var actionAttempt = seam.accessMethods().encode( - AccessMethodsEncodeRequest.builder() +var actionAttempt = seam.accessMethods().assignCard( + AccessMethodsAssignCardRequest.builder() .accessMethodId("a1b2c3d4-e5f6-7890-abcd-ef1234567890") - .acsEncoderId("encoder-001") + .cardNumber("ABCD1234") .build() ); ``` ```bash cURL curl -X 'POST' \ - 'https://connect.getseam.com/access_methods/encode' \ + 'https://connect.getseam.com/access_methods/assign_card' \ -H "Authorization: Bearer ${SEAM_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "acs_encoder_id": "encoder-001" + "card_number": "ABCD1234" }' ``` From aacdaff2a46ff60164bb8658a969c546c0b116c3 Mon Sep 17 00:00:00 2001 From: dawnho Date: Wed, 10 Jun 2026 13:35:53 -0700 Subject: [PATCH 36/36] feat: add missing Ruby, PHP, C#, Java samples to get_related sections All five delivery pages (PIN codes, mobile keys, key cards, cloud keys, instant keys) had get_related code blocks with only JS, Python, and cURL. Added the four missing languages to each. Co-Authored-By: Claude Opus 4.6 --- .../granting-access/using-cloud-keys.mdx | 32 +++++++++++++++++ .../granting-access/using-instant-keys.mdx | 32 +++++++++++++++++ .../granting-access/using-key-cards.mdx | 32 +++++++++++++++++ .../granting-access/using-mobile-keys.mdx | 32 +++++++++++++++++ .../granting-access/using-pin-codes.mdx | 35 +++++++++++++++++++ 5 files changed, 163 insertions(+) diff --git a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx index 25d4086f5..46c287f31 100644 --- a/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-cloud-keys.mdx @@ -229,6 +229,38 @@ related = seam.access_methods.get_related( print(related.acs_entrances) # entrances this cloud key can unlock ``` +```ruby Ruby +related = seam.access_methods.get_related( + access_method_ids: [access_method.access_method_id] +) + +puts related.acs_entrances # entrances this cloud key can unlock +``` + +```php PHP +$related = $seam->access_methods->get_related( + access_method_ids: [$accessMethod->access_method_id] +); + +echo json_encode($related->acs_entrances); // entrances this cloud key can unlock +``` + +```csharp C# +var related = seam.AccessMethods.GetRelated( + accessMethodIds: new List { accessMethod.AccessMethodId } +); + +// related.AcsEntrances — entrances this cloud key can unlock +``` + +```java Java +var related = seam.accessMethods().getRelated( + AccessMethodsGetRelatedRequest.builder() + .accessMethodIds(List.of(accessMethod.getAccessMethodId())) + .build() +); +``` + ```bash cURL curl -X 'POST' \ 'https://connect.getseam.com/access_methods/get_related' \ diff --git a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx index c6f341b47..315cf23d8 100644 --- a/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-instant-keys.mdx @@ -286,6 +286,38 @@ related = seam.access_methods.get_related( print(related.acs_entrances) # ACS entrances this Instant Key unlocks ``` +```ruby Ruby +related = seam.access_methods.get_related( + access_method_ids: [access_method.access_method_id] +) + +puts related.acs_entrances # ACS entrances this Instant Key unlocks +``` + +```php PHP +$related = $seam->access_methods->get_related( + access_method_ids: [$accessMethod->access_method_id] +); + +echo json_encode($related->acs_entrances); // ACS entrances this Instant Key unlocks +``` + +```csharp C# +var related = seam.AccessMethods.GetRelated( + accessMethodIds: new List { accessMethod.AccessMethodId } +); + +// related.AcsEntrances — ACS entrances this Instant Key unlocks +``` + +```java Java +var related = seam.accessMethods().getRelated( + AccessMethodsGetRelatedRequest.builder() + .accessMethodIds(List.of(accessMethod.getAccessMethodId())) + .build() +); +``` + ```bash cURL curl -X 'POST' \ 'https://connect.getseam.com/access_methods/get_related' \ diff --git a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx index 3fcae6b33..4f31b1f60 100644 --- a/mintlify-docs/use-cases/granting-access/using-key-cards.mdx +++ b/mintlify-docs/use-cases/granting-access/using-key-cards.mdx @@ -450,6 +450,38 @@ related = seam.access_methods.get_related( print(related.acs_entrances) # entrances this card unlocks ``` +```ruby Ruby +related = seam.access_methods.get_related( + access_method_ids: [access_method.access_method_id] +) + +puts related.acs_entrances # entrances this card unlocks +``` + +```php PHP +$related = $seam->access_methods->get_related( + access_method_ids: [$accessMethod->access_method_id] +); + +echo json_encode($related->acs_entrances); // entrances this card unlocks +``` + +```csharp C# +var related = seam.AccessMethods.GetRelated( + accessMethodIds: new List { accessMethod.AccessMethodId } +); + +// related.AcsEntrances — entrances this card unlocks +``` + +```java Java +var related = seam.accessMethods().getRelated( + AccessMethodsGetRelatedRequest.builder() + .accessMethodIds(List.of(accessMethod.getAccessMethodId())) + .build() +); +``` + ```bash cURL curl -X 'POST' \ 'https://connect.getseam.com/access_methods/get_related' \ diff --git a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx index d2b082085..a4654b722 100644 --- a/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx +++ b/mintlify-docs/use-cases/granting-access/using-mobile-keys.mdx @@ -327,6 +327,38 @@ related = seam.access_methods.get_related( print(related.acs_entrances) # ACS entrances this mobile key unlocks ``` +```ruby Ruby +related = seam.access_methods.get_related( + access_method_ids: [access_method.access_method_id] +) + +puts related.acs_entrances # ACS entrances this mobile key unlocks +``` + +```php PHP +$related = $seam->access_methods->get_related( + access_method_ids: [$accessMethod->access_method_id] +); + +echo json_encode($related->acs_entrances); // ACS entrances this mobile key unlocks +``` + +```csharp C# +var related = seam.AccessMethods.GetRelated( + accessMethodIds: new List { accessMethod.AccessMethodId } +); + +// related.AcsEntrances — ACS entrances this mobile key unlocks +``` + +```java Java +var related = seam.accessMethods().getRelated( + AccessMethodsGetRelatedRequest.builder() + .accessMethodIds(List.of(accessMethod.getAccessMethodId())) + .build() +); +``` + ```bash cURL curl -X 'POST' \ 'https://connect.getseam.com/access_methods/get_related' \ diff --git a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx index b7b7ec3c9..edc885892 100644 --- a/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx +++ b/mintlify-docs/use-cases/granting-access/using-pin-codes.mdx @@ -413,6 +413,41 @@ print(related.devices) # devices this PIN code is programmed on print(related.acs_entrances) # ACS entrances this PIN code unlocks ``` +```ruby Ruby +related = seam.access_methods.get_related( + access_method_ids: [access_method.access_method_id] +) + +puts related.devices # devices this PIN code is programmed on +puts related.acs_entrances # ACS entrances this PIN code unlocks +``` + +```php PHP +$related = $seam->access_methods->get_related( + access_method_ids: [$accessMethod->access_method_id] +); + +echo json_encode($related->devices); // devices this PIN code is programmed on +echo json_encode($related->acs_entrances); // ACS entrances this PIN code unlocks +``` + +```csharp C# +var related = seam.AccessMethods.GetRelated( + accessMethodIds: new List { accessMethod.AccessMethodId } +); + +// related.Devices — devices this PIN code is programmed on +// related.AcsEntrances — ACS entrances this PIN code unlocks +``` + +```java Java +var related = seam.accessMethods().getRelated( + AccessMethodsGetRelatedRequest.builder() + .accessMethodIds(List.of(accessMethod.getAccessMethodId())) + .build() +); +``` + ```bash cURL curl -X 'POST' \ 'https://connect.getseam.com/access_methods/get_related' \