Create an Access Grant

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.

• Request Parameters

• Response

• Examples

Creates a new Access Grant.

JavaScript

Creates a new Access Grant using space IDs and an existing user identity.

Code:

await seam.accessGrants.create({
  user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4",
  space_ids: [
    "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
  ],
  requested_access_methods: [
    { mode: "code" },
    { mode: "card" },
    { mode: "mobile_key" },
  ],
  starts_at: "2025-06-16T16:54:17.946606Z",
  ends_at: "2025-06-18T16:54:17.946606Z",
});

Output:

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

cURL

Python

Ruby

PHP

Seam CLI

Authentication Methods

• API key

• Client session token

• Personal access token Must also include the seam-workspace header in the request.

To learn more, see Authentication.

Request Parameters

requested_access_methods Array of Objects (Required)

code String

Specific PIN code to use for this access method. Only applicable when mode is 'code'.

---

mode Enum

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

Enum values:

• code

• card

• mobile_key

---

access_grant_key String

Unique key for the access grant within the workspace.

---

acs_entrance_ids Array of UUIDs

Set of IDs of the entrances to which access is being granted.

---

customization_profile_id String

ID of the customization profile to apply to the Access Grant and its access methods.

---

device_ids Array of UUIDs

Set of IDs of the devices to which access is being granted.

---

ends_at String

Date and time at which the validity of the new grant ends, in ISO 8601 format. Must be a time in the future and after starts_at.

---

location Object

When used, creates a new location with the given entrances and devices, and gives the user access to this location.

acs_entrance_ids List

Deprecated. Use acs_entrance_ids at the top level.

---

device_ids List

Deprecated. Use device_ids at the top level.

---

name String

Name of the location.

---

location_ids Array of UUIDs

Deprecated. Use space_ids.

---

name String

Name for the access grant.

---

reservation_key String

Reservation key for the access grant.

---

space_ids Array of UUIDs

Set of IDs of existing spaces to which access is being granted.

---

space_keys Array of Strings

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

---

user_identity Object

When used, creates a new user identity with the given details, and grants them access.

email_address String

Unique email address for the user identity.

---

full_name String

---

phone_number String

Unique phone number for the user identity in E.164 format (for example, [phone]).

---

user_identity_key String

Unique key for the user identity.

---

user_identity_id String

ID of user identity for whom access is being granted.

---

Response

access_grant

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"
}

---

Examples

Create an Access Grant using entrances and devices

Creates a new Access Grant using entrance IDs and device IDs and an existing user identity.

JavaScript

Code:

await seam.accessGrants.create({
  user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4",
  acs_entrance_ids: [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "550e8400-e29b-41d4-a716-446655440001",
  ],
  device_ids: [
    "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
    "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  ],
  requested_access_methods: [
    { mode: "code" },
    { mode: "card" },
    { mode: "mobile_key" },
  ],
  starts_at: "2025-06-16T16:54:17.946606Z",
  ends_at: "2025-06-18T16:54:17.946606Z",
});

Output:

{
  "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"
  ]
}

cURL

Python

Ruby

PHP

Seam CLI

---

Create an Access Grant including a new user identity

Creates a new Access Grant and create a new user identity as part of the same operation.

JavaScript

Code:

await seam.accessGrants.create({
  user_identity: {
    full_name: "Jane Doe",
    email_address: "[email protected]",
    phone_number: "[phone]",
  },
  space_ids: [
    "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "7f8e9d0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
  ],
  requested_access_methods: [
    { mode: "code" },
    { mode: "card" },
    { mode: "mobile_key" },
  ],
  starts_at: "2025-06-16T16:54:17.946606Z",
  ends_at: "2025-06-18T16:54:17.946606Z",
});

Output:

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

cURL

Python

Ruby

PHP

Seam CLI