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.

Creates a new access grant.

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",
  "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"
}
Authentication Methods
  • API key

  • 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)


acs_entrance_ids Array of UUIDs

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


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

device_ids List

name String

Name of the location.


location_ids Array of UUIDs


space_ids Array of UUIDs

Set of IDs 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, +15555550100).


user_identity_id String

ID of user identity for whom access is being granted.


Response

access_grant

{
  "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",
  "location_ids": [
    "9e8d7c6b-5a4b-3c2d-1e0f-9a8b7c6d5e4f",
    "f0e1d2c3-b4a5-6d7e-8f90-1a2b3c4d5e6f"
  ],
  "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"
  ],
  "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.

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

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.

Code

await seam.accessGrants.create({
  user_identity: {
    full_name: "Jane Doe",
    email_address: "[email protected]",
    phone_number: "+1555551003",
  },
  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",
  "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"
}

Last updated

Was this helpful?