--- title: "Create an Access Grant" method: POST path: "/access_grants/create" --- # Create an Access Grant `POST /access_grants/create` Creates a new [Access Grant](/use-cases/granting-access). Access Grants are the default and recommended way to grant a user access to any physical space, irrespective of the locking hardware. They work with both standalone smart locks (using `device_ids`) and access control systems (using `acs_entrance_ids` or `space_ids`), and can issue PIN codes, key cards, and mobile keys through a single request. ## Request body - union - object - `user_identity_id` string, uuid, required — ID of user identity for whom access is being granted. - `access_grant_key` string — Unique key for the access grant within the workspace. - `acs_entrance_ids` string[] — Set of IDs of the [entrances](/api/acs/systems/list) to which access is being granted. - `customization_profile_id` string, uuid — ID of the customization profile to apply to the Access Grant and its access methods. - `device_ids` string[] — Set of IDs of the [devices](/api/devices/list) to which access is being granted. - `ends_at` string, nullable — Date and time at which the validity of the new grant ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Must be a time in the future and after `starts_at`. - `location` object — Deprecated. Create a space first, then reference it using `space_ids`. - `acs_entrance_ids` string[] — Deprecated. Use `acs_entrance_ids` at the top level. - `device_ids` string[] — Deprecated. Use `device_ids` at the top level. - `name` string — Name of the location. - `location_ids` string[] — Deprecated. Use `space_ids`. - `name` string, nullable — Name for the access grant. - `requested_access_methods` object[], required - `code` string — Specific PIN code to use for this access method. Only applicable when mode is 'code'. - `instant_key_max_use_count` integer — Maximum number of times the instant key can be used. Only applicable when mode is 'mobile_key'. Defaults to 1 if not specified. - `mode` 'code' | 'card' | 'mobile_key' | 'cloud_key', required — Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`. - `reservation_key` string — Reservation key for the access grant. - `space_ids` string[] — Set of IDs of existing spaces to which access is being granted. - `space_keys` string[] — Set of keys of existing spaces to which access is being granted. - `starts_at` string — Date and time at which the validity of the new grant starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. - object - `user_identity` object, required — When used, creates a new user identity with the given details, and grants them access. - `email_address` string, email, nullable — Unique email address for the user identity. - `full_name` string, nullable — Full name of the user associated with the user identity. - `phone_number` string, nullable — Unique phone number for the user identity in [E.164 format](https://www.itu.int/rec/T-REC-E.164/en) (for example, +15555550100). - `user_identity_key` string, nullable — Unique key for the user identity. - `access_grant_key` string — Unique key for the access grant within the workspace. - `acs_entrance_ids` string[] — Set of IDs of the [entrances](/api/acs/systems/list) to which access is being granted. - `customization_profile_id` string, uuid — ID of the customization profile to apply to the Access Grant and its access methods. - `device_ids` string[] — Set of IDs of the [devices](/api/devices/list) to which access is being granted. - `ends_at` string, nullable — Date and time at which the validity of the new grant ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Must be a time in the future and after `starts_at`. - `location` object — Deprecated. Create a space first, then reference it using `space_ids`. - `acs_entrance_ids` string[] — Deprecated. Use `acs_entrance_ids` at the top level. - `device_ids` string[] — Deprecated. Use `device_ids` at the top level. - `name` string — Name of the location. - `location_ids` string[] — Deprecated. Use `space_ids`. - `name` string, nullable — Name for the access grant. - `requested_access_methods` object[], required - `code` string — Specific PIN code to use for this access method. Only applicable when mode is 'code'. - `instant_key_max_use_count` integer — Maximum number of times the instant key can be used. Only applicable when mode is 'mobile_key'. Defaults to 1 if not specified. - `mode` 'code' | 'card' | 'mobile_key' | 'cloud_key', required — Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`. - `reservation_key` string — Reservation key for the access grant. - `space_ids` string[] — Set of IDs of existing spaces to which access is being granted. - `space_keys` string[] — Set of keys of existing spaces to which access is being granted. - `starts_at` string — Date and time at which the validity of the new grant starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. ## Response `200` OK - object - `access_grant` AccessGrant, required — 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. See the [access_grant object](/api/access_grants/object). - `access_grant_id` string, uuid, required — ID of the Access Grant. - `access_grant_key` string — Unique key for the access grant within the workspace. - `access_method_ids` string[], required — 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` string, date-time, required — Date and time at which the Access Grant was created. - `customization_profile_id` string, uuid — ID of the customization profile associated with the Access Grant. - `display_name` string, required — Display name of the Access Grant. - `ends_at` string, date-time, nullable, required — Date and time at which the Access Grant ends. - `errors` object[], required — Errors associated with the [access grant](/use-cases/granting-access). - `created_at` string, date-time, required — Date and time at which Seam created the error. - `error_code` 'cannot_create_requested_access_methods', required — Unique identifier of the type of error. Enables quick recognition and categorization of the issue. - `message` string, required — Detailed description of the error. Provides insights into the issue and potentially how to rectify it. - `missing_device_ids` string[] — IDs of the devices that did not receive an access code at grant creation. Use these to identify which specific devices failed when the message reports a partial failure. - `instant_key_url` string, uri — Instant Key URL. Only returned if the Access Grant has a single mobile_key access_method. - `location_ids` string[], required — Deprecated. Use `space_ids`. - `name` string, nullable, required — Name of the Access Grant. If not provided, the display name will be computed. - `pending_mutations` union[], required — List of pending mutations for the access grant. This shows updates that are in progress. - union - object — Seam is in the process of updating the devices/spaces associated with this access grant. - `created_at` string, date-time, required — Date and time at which the mutation was created. - `from` object, required — Previous location configuration. - `device_ids` string[], required — Previous device IDs where access codes existed. - `message` string, required — Detailed description of the mutation. - `mutation_code` 'updating_spaces', required — Mutation code to indicate that Seam is in the process of updating the spaces (devices) associated with this access grant. - `to` object, required — New location configuration. - `common_code_key` string, nullable — Common code key to ensure PIN code reuse across devices. - `device_ids` string[], required — New device IDs where access codes should be created. - object — Seam is in the process of updating the access times for this access grant. - `access_method_ids` string[], required — IDs of the access methods being updated. - `created_at` string, date-time, required — Date and time at which the mutation was created. - `from` object, required — Previous access time configuration. - `ends_at` string, date-time, nullable, required — Previous end time for access. - `starts_at` string, date-time, nullable, required — Previous start time for access. - `message` string, required — Detailed description of the mutation. - `mutation_code` 'updating_access_times', required — Mutation code to indicate that Seam is in the process of updating the access times for this access grant. - `to` object, required — New access time configuration. - `ends_at` string, date-time, nullable, required — New end time for access. - `starts_at` string, date-time, nullable, required — New start time for access. - `requested_access_methods` object[], required — Access methods that the user requested for the Access Grant. - `code` string — Specific PIN code to use for this access method. Only applicable when mode is 'code'. - `created_access_method_ids` string[], required — IDs of the access methods created for the requested access method. - `created_at` string, date-time, required — Date and time at which the requested access method was added to the Access Grant. - `display_name` string, required — Display name of the access method. - `instant_key_max_use_count` integer — Maximum number of times the instant key can be used. Only applicable when mode is 'mobile_key'. Defaults to 1 if not specified. - `mode` 'code' | 'card' | 'mobile_key' | 'cloud_key', required — Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`. - `reservation_key` string — Reservation key for the access grant. - `space_ids` string[], required — IDs of the spaces to which the Access Grant gives access. - `starts_at` string, date-time, required — Date and time at which the Access Grant starts. - `user_identity_id` string, uuid, required — ID of user identity to which the Access Grant gives access. - `warnings` object[], required — Warnings associated with the [access grant](/use-cases/granting-access). - `error_code` string — Error or warning code. - `message` string — Human-readable description. - `created_at` string, date-time — When this error or warning was generated. - `workspace_id` string, uuid, required — ID of the Seam workspace associated with the Access Grant. ## Other responses - `400` — Bad Request - `401` — Unauthorized --- [API](https://skmtc.net/seam/apis/seam-connect.md) · [All operations](https://skmtc.net/seam/apis/seam-connect/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/seam/seam-connect/versions/00c35395ce12/schema)