Using Access Grants to Issue Instant Keys

Learn how to create an Access Grant that issues an Instant Key.

An Access Grant defines the "who, where, when, and how" for assigning a user access to entrances, including the following characteristics:

Characteristic	Creation Parameter	Description
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	acs_entrance_ids	The entrances to which to grant access. You can specify one or more entrances 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).

Once you have identified the entrances to which you want to grant a user access, create an Access Grant to assign the specified access to the user. Specify mobile_key as the mode for a requested access method, and the resulting mobile key also includes an Instant Key.

To create an Instant Key:

1. Identify the entrances to which you want to grant the user access.

2. 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 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, including a mobile key.

The action returns an Access Grant that includes the Instant Key URL. You can then share this Instant Key URL with your user.

---

Identify Entrances

List the entrances in the access system and identify the ones to which you want to grant the user access.

JavaScript

Code

await seam.acs.entrances.list({
  acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
});

Output

[
  {
    "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",
    ...
  },
  ...
]

cURL

Python

Ruby

PHP

Seam CLI

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. Also, include the ID of the access system in which you want to grant the user access.

JavaScript

Code

await seam.userIdentities.create({
  full_name: "Jane Doe",
  email_address: "[email protected]",
  acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"],
});

Output

{
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "full_name": "Jane Doe",
  "email_address": "[email protected]",
  ...
}

cURL

Python

Ruby

PHP

Seam CLI

---

Create an Access Grant

To create an Access Grant, specify the user identity, entrance IDs, starting and ending times, and requested access methods. To issue an Instant Key, specify mobile_key as the mode for a requested access method.

JavaScript

Code

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: "[email protected]",
  // },
  acs_entrance_ids: [
    "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
    "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

{
  "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": "Mobile Key Credential",
      "mode": "mobile_key",
      "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
      ...
    }
  ],
  "instant_key_url": "https://ik.seam.co/THSDKS",
  ...
}

cURL

Python

Ruby

PHP

Seam CLI

Within the response, the instant_key_url property provides the issued Instant Key. Share this URL with your user. For details, see Delivering Instant Keys.