# Access Grants

{% hint style="info" %}
**Early Access Preview.** The Access Grants API is currently in Alpha. We're actively developing it and seeking early feedback at <support@seam.co>. Expect breaking changes as we refine the design.
{% endhint %}

## The access\_grant Object

* [Properties](#properties)
* [Warnings](#warnings)
* [Events](#events)
* [Endpoints](#endpoints)

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.

{% tabs %}
{% tab title="Access Grant" %}
An Access Grant resource.

```json
{
  "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"
}
```

{% endtab %}
{% endtabs %}

***

## 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.

***

**`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*

{% hint style="warning" %}
**Deprecated**. Use `space_ids`.
{% endhint %}

***

**`name`** *String*

Name of the Access Grant. If not provided, the display name will be computed.

***

**`requested_access_methods`** *List* *of Objects*

Access methods that the user requested for the Access Grant.

<details>

<summary>Child Object Properties</summary>

**`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.

**`mode`** *Enum*

Access method mode. Supported values: `code`, `card`, `mobile_key`.

</details>

***

**`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`**](#warnings) *List* *of Objects*

Warnings associated with the [access grant](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/capability-guides/access-grants).

The specific structure of each object in this list depends on the value of its `warning_code` field.

Variants:

<details>

<summary><code>being_deleted</code></summary>

Indicates that the [access grant](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/capability-guides/access-grants) 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`

</details>

***

**`workspace_id`** *UUID*

ID of the Seam workspace associated with the Access Grant.

***

## Warnings

**`being_deleted`**

Indicates that the [access grant](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/capability-guides/access-grants) is being deleted.

***

## Events

**`access_grant.created`**

An Access Grant was created.

<details>

<summary>Properties</summary>

**`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](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/core-concepts/workspaces) associated with the event.

</details>

***

**`access_grant.deleted`**

An Access Grant was deleted.

<details>

<summary>Properties</summary>

**`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](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/core-concepts/workspaces) associated with the event.

</details>

***

**`access_grant.access_granted_to_all_doors`**

All access requested for an Access Grant was successfully granted.

<details>

<summary>Properties</summary>

**`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](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/core-concepts/workspaces) associated with the event.

</details>

***

**`access_grant.access_granted_to_door`**

Access requested as part of an Access Grant to a particular door was successfully granted.

<details>

<summary>Properties</summary>

**`access_grant_id`** *UUID*

ID of the affected Access Grant.

**`acs_entrance_id`** *UUID*

ID of the affected [entrance](https://docs.seam.co/latest/capability-guides/retrieving-entrance-details).

**`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](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/core-concepts/workspaces) associated with the event.

</details>

***

**`access_grant.access_to_door_lost`**

Access to a particular door that was requested as part of an Access Grant was lost.

<details>

<summary>Properties</summary>

**`access_grant_id`** *UUID*

ID of the affected Access Grant.

**`acs_entrance_id`** *UUID*

ID of the affected [entrance](https://docs.seam.co/latest/capability-guides/retrieving-entrance-details).

**`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](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/core-concepts/workspaces) associated with the event.

</details>

***

**`access_grant.access_times_changed`**

An Access Grant's start or end time was changed.

<details>

<summary>Properties</summary>

**`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](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/core-concepts/workspaces) associated with the event.

</details>

***

## Endpoints

[**`/access_grants/create`**](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/api/access_grants/create)

Creates a new Access Grant.

[**`/access_grants/delete`**](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/api/access_grants/delete)

Delete an Access Grant.

[**`/access_grants/get`**](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/api/access_grants/get)

Get an Access Grant.

[**`/access_grants/get_related`**](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/api/access_grants/get_related)

Gets all related resources for one or more Access Grants.

[**`/access_grants/list`**](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/api/access_grants/list)

Gets an Access Grant.

[**`/access_grants/request_access_methods`**](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/api/access_grants/request_access_methods)

Adds additional requested access methods to an existing Access Grant.

[**`/access_grants/update`**](https://docs.seam.co/latest/~/revisions/WnT0iExlRmVG3JXMNm4C/api/access_grants/update)

Updates an existing Access Grant's time window.