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.
Early Access Preview. The Access Grants API is currently in Alpha. We're actively developing it and seeking early feedback at [email protected]. Expect breaking changes as we refine the design.
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.
When creating an Access Grant, you can specify the spaces to which you want to grant access.
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. 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.
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.
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.
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 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 and the system integration guide for your access system.
Create one or more spaces to group the entrances to which you want to grant access. For details, see Spaces and Create a Space.
Identify Spaces
List the spaces and identify the ones to which you want to grant the user access.
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.
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:
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]",
# },
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"
)
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.
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:
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.
