Sign UpSupported Devices

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
Description

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.

acs_entrance_ids

The entrances to which to grant access. You can specify one or more entrances by ID.

starts_at and ends_at

The access schedule.

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.

Code

seam.acs.entrances.list(
  acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339"
)

Output

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

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.

Code

seam.user_identities.create(
  full_name="Jane Doe",
  email_address="[email protected]",
  acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"]
)

Output

UserIdentity(
  user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
  full_name="Jane Doe",
  email_address="[email protected]",
  ...
)

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.

Code

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": "[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

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

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.

PreviousSetting Up Your Site for Instant KeysNextUsing Seam Console to Issue Instant Keys

Last updated

Was this helpful?