Access Grants
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.
The access_grant Object
Represents an Access Grant. Access Grants enable you to grant a user identity access to spaces, entrances, and devices through one or more access methods, such as mobile keys, plastic cards, and PIN codes. You can create an Access Grant for an existing user identity, or you can create a new user identity while creating the new Access Grant.
An Access Grant resource.
{
"access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
"access_method_ids": [
"a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d",
"5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
"c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"
],
"created_at": "2025-06-16T16:54:17.946606Z",
"display_name": "My Access Grant",
"ends_at": "2025-06-18T16:54:17.946606Z",
"instant_key_url": "https://ik.seam.co/ABCXYZ",
"requested_access_methods": [
{
"display_name": "PIN Code Credential",
"mode": "code",
"created_at": "2025-06-16T16:54:17.946606Z",
"created_access_method_ids": ["a1b2c3d4-e5f6-4a3b-2c1d-0e9f8a7b6c5d"]
},
{
"display_name": "Card Credential",
"mode": "card",
"created_at": "2025-06-16T16:54:19.946606Z",
"created_access_method_ids": ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f"]
},
{
"display_name": "Mobile Key Credential",
"mode": "mobile_key",
"created_at": "2025-06-16T16:54:21.946606Z",
"created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"]
}
],
"space_ids": [
"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a"
],
"starts_at": "2025-06-16T16:54:17.946606Z",
"user_identity_id": "e3d736c1-540d-4d10-83e5-9a4e135453b4",
"workspace_id": "750fc0bc-4450-4356-8d9f-18c6a3a6b2c7"
}Properties
access_grant_id UUID
ID of the Access Grant.
access_grant_key String
Unique key for the access grant within the workspace.
access_method_ids List of UUIDs
IDs of the access methods created for the Access Grant.
client_session_token String
Client Session Token. Only returned if the Access Grant has a mobile_key access method.
created_at Datetime
Date and time at which the Access Grant was created.
customization_profile_id UUID
ID of the customization profile associated with the Access Grant.
display_name String
Display name of the Access Grant.
ends_at Datetime
Date and time at which the Access Grant ends.
errors List of Objects
Errors associated with the access grant.
The specific structure of each object in this list depends on the value of its error_code field.
Variants:
cannot_create_requested_access_methods
created_at Datetime
Date and time at which Seam created the error.
error_code Enum
Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
Enum values:
cannot_create_requested_access_methods
message String
Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
instant_key_url String
Instant Key URL. Only returned if the Access Grant has a single mobile_key access_method.
location_ids List of UUIDs
Deprecated. Use space_ids.
name String
Name of the Access Grant. If not provided, the display name will be computed.
pending_mutations List of Objects
List of pending mutations for the access grant. This shows updates that are in progress.
The specific structure of each object in this list depends on the value of its mutation_code field.
Variants:
updating_spaces
Seam is in the process of updating the devices/spaces associated with this access grant.
created_at Datetime
Date and time at which the mutation was created.
from Object
Previous location configuration.
Child Properties
device_idsList of UUIDsPrevious device IDs where access codes existed.
message String
Detailed description of the mutation.
mutation_code Enum
Mutation code to indicate that Seam is in the process of updating the spaces (devices) associated with this access grant.
Enum values:
updating_spaces
to Object
New location configuration.
Child Properties
common_code_keyStringCommon code key to ensure PIN code reuse across devices.
device_idsList of UUIDsNew device IDs where access codes should be created.
updating_access_times
Seam is in the process of updating the access times for this access grant.
access_method_ids List of UUIDs
IDs of the access methods being updated.
created_at Datetime
Date and time at which the mutation was created.
from Object
Previous access time configuration.
Child Properties
ends_atDatetimePrevious end time for access.
starts_atDatetimePrevious start time for access.
message String
Detailed description of the mutation.
mutation_code Enum
Mutation code to indicate that Seam is in the process of updating the access times for this access grant.
Enum values:
updating_access_times
to Object
New access time configuration.
Child Properties
ends_atDatetimeNew end time for access.
starts_atDatetimeNew start time for access.
requested_access_methods List of Objects
Access methods that the user requested for the Access Grant.
Child Object Properties
code String
Specific PIN code to use for this access method. Only applicable when mode is 'code'.
created_access_method_ids List of UUIDs
IDs of the access methods created for the requested access method.
created_at Datetime
Date and time at which the requested access method was added to the Access Grant.
display_name String
Display name of the access method.
instant_key_max_use_count Number
Maximum number of times the instant key can be used. Only applicable when mode is 'mobile_key'. Defaults to 1 if not specified.
mode Enum
Access method mode. Supported values: code, card, mobile_key.
reservation_key String
Reservation key for the access grant.
space_ids List of UUIDs
IDs of the spaces to which the Access Grant gives access.
starts_at Datetime
Date and time at which the Access Grant starts.
user_identity_id UUID
ID of user identity to which the Access Grant gives access.
warnings List of Objects
Warnings associated with the access grant.
The specific structure of each object in this list depends on the value of its warning_code field.
Variants:
being_deleted
Indicates that the access grant is being deleted.
created_at Datetime
Date and time at which Seam created the warning.
message String
Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
warning_code Enum
Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
Enum values:
being_deleted
underprovisioned_access
Indicates that the access grant should have access to more locations than it currently does. Access methods are being created for the missing locations.
created_at Datetime
Date and time at which Seam created the warning.
message String
Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
warning_code Enum
Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
Enum values:
underprovisioned_access
overprovisioned_access
Indicates that the access grant has access to locations it should not have. Access methods are being removed from the extra locations.
created_at Datetime
Date and time at which Seam created the warning.
message String
Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
warning_code Enum
Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
Enum values:
overprovisioned_access
updating_access_times
Indicates that the access times for this access grant are being updated.
access_method_ids List of UUIDs
IDs of the access methods being updated.
created_at Datetime
Date and time at which Seam created the warning.
message String
Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
warning_code Enum
Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
Enum values:
updating_access_times
requested_code_unavailable
Indicates that the requested PIN code was already in use on a device, so a different code was assigned.
created_at Datetime
Date and time at which Seam created the warning.
device_id UUID
ID of the device where the requested code was unavailable.
message String
Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
new_code String
The new PIN code that was assigned instead.
original_code String
The originally requested PIN code that was unavailable.
warning_code Enum
Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
Enum values:
requested_code_unavailable
device_does_not_support_access_codes
Indicates that a device in the access grant does not support access codes and was excluded from code materialization.
created_at Datetime
Date and time at which Seam created the warning.
device_id UUID
ID of the device that does not support access codes.
message String
Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
warning_code Enum
Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
Enum values:
device_does_not_support_access_codes
workspace_id UUID
ID of the Seam workspace associated with the Access Grant.
Errors
cannot_create_requested_access_methods
Warnings
being_deleted
Indicates that the access grant is being deleted.
device_does_not_support_access_codes
Indicates that a device in the access grant does not support access codes and was excluded from code materialization.
overprovisioned_access
Indicates that the access grant has access to locations it should not have. Access methods are being removed from the extra locations.
requested_code_unavailable
Indicates that the requested PIN code was already in use on a device, so a different code was assigned.
underprovisioned_access
Indicates that the access grant should have access to more locations than it currently does. Access methods are being created for the missing locations.
updating_access_times
Indicates that the access times for this access grant are being updated.
Events
access_grant.created
An Access Grant was created.
Properties
access_grant_id UUID
ID of the affected Access Grant.
created_at Datetime
Date and time at which the event was created.
event_id UUID
ID of the event.
event_type Enum
Value: access_grant.created
occurred_at Datetime
Date and time at which the event occurred.
workspace_id UUID
ID of the workspace associated with the event.
access_grant.deleted
An Access Grant was deleted.
Properties
access_grant_id UUID
ID of the affected Access Grant.
created_at Datetime
Date and time at which the event was created.
event_id UUID
ID of the event.
event_type Enum
Value: access_grant.deleted
occurred_at Datetime
Date and time at which the event occurred.
workspace_id UUID
ID of the workspace associated with the event.
access_grant.access_granted_to_all_doors
All access requested for an Access Grant was successfully granted.
Properties
access_grant_id UUID
ID of the affected Access Grant.
created_at Datetime
Date and time at which the event was created.
event_id UUID
ID of the event.
event_type Enum
Value: access_grant.access_granted_to_all_doors
occurred_at Datetime
Date and time at which the event occurred.
workspace_id UUID
ID of the workspace associated with the event.
access_grant.access_granted_to_door
Access requested as part of an Access Grant to a particular door was successfully granted.
Properties
access_grant_id UUID
ID of the affected Access Grant.
acs_entrance_id UUID
ID of the affected entrance.
created_at Datetime
Date and time at which the event was created.
event_id UUID
ID of the event.
event_type Enum
Value: access_grant.access_granted_to_door
occurred_at Datetime
Date and time at which the event occurred.
workspace_id UUID
ID of the workspace associated with the event.
access_grant.access_to_door_lost
Access to a particular door that was requested as part of an Access Grant was lost.
Properties
access_grant_id UUID
ID of the affected Access Grant.
acs_entrance_id UUID
ID of the affected entrance.
created_at Datetime
Date and time at which the event was created.
event_id UUID
ID of the event.
event_type Enum
Value: access_grant.access_to_door_lost
occurred_at Datetime
Date and time at which the event occurred.
workspace_id UUID
ID of the workspace associated with the event.
access_grant.access_times_changed
An Access Grant's start or end time was changed.
Properties
access_grant_id UUID
ID of the affected Access Grant.
access_grant_key String
Key of the affected Access Grant (if present).
created_at Datetime
Date and time at which the event was created.
ends_at String
The new end time for the access grant.
event_id UUID
ID of the event.
event_type Enum
Value: access_grant.access_times_changed
occurred_at Datetime
Date and time at which the event occurred.
starts_at String
The new start time for the access grant.
workspace_id UUID
ID of the workspace associated with the event.
access_grant.could_not_create_requested_access_methods
One or more requested access methods could not be created for an Access Grant.
Properties
access_grant_id UUID
ID of the affected Access Grant.
created_at Datetime
Date and time at which the event was created.
error_message String
Description of why the access methods could not be created.
event_id UUID
ID of the event.
event_type Enum
Value: access_grant.could_not_create_requested_access_methods
occurred_at Datetime
Date and time at which the event occurred.
workspace_id UUID
ID of the workspace associated with the event.
Endpoints
Creates a new Access Grant.
Delete an Access Grant.
Get an Access Grant.
Gets all related resources for one or more Access Grants.
Gets an Access Grant.
/access_grants/request_access_methods
Adds additional requested access methods to an existing Access Grant.
Updates an existing Access Grant's time window.
Last updated
Was this helpful?