Creating an Access Grant

An Access Grant is a single API call that defines who gets access, where they can go, when access is valid, and how they get in. This guide walks through the full flow from creation to delivery.

Before You Begin

A Seam workspace with at least one connected device or access system. You can use a sandbox workspace with test devices.
An API key.
The Seam SDK installed in your language of choice (see Quick Start).

Step 1: Create the Access Grant

Call /access_grants/create with four things:

Who — a user_identity_id for an existing user, or pass user_identity to create one inline
Where — the resources to grant access to
When — the access schedule (starts_at and ends_at)
How — the access method modes to issue (e.g., code, mobile_key, card, cloud_key)

Choosing Resources

You specify where to grant access using one or more of these parameters:

Parameter	Best for	Description
`device_ids`	Standalone smart locks	Pass IDs of individual devices like August, Yale, or Schlage locks connected through a Connect Webview.
`space_ids`	Grouped access points	Grant access to all entrances and devices in one or more spaces. Useful when a guest needs access to a room door, lobby, and elevator in one call.
`acs_entrance_ids`	Access control system entrances	Pass IDs of individual ACS entrances for fine-grained control.

You can combine these in a single Access Grant — for example, a standalone smart lock (device_ids) plus a set of ACS entrances (acs_entrance_ids).

If you’re using Dormakaba Ambiance, Dormakaba Community, Visionline, Salto Space, or Vostio, you’ll also need to pass a reservation_key to coordinate credential override sequencing. See Reservation Access Grants.

If you create multiple Access Grants for the same user_identity_id, Seam tries to reuse the same access methods across grants — for example, assigning the same PIN code so the user doesn’t have to learn a new one for each reservation.

When an Access Grant provisions a PIN code on a standalone lock, some devices only accept certain access schedules — for example, a minimum or maximum duration, or fixed check-in and check-out times. Before setting starts_at and ends_at, review the device’s time frame options so that your schedule is valid. See Understanding Time Frame Options.

Example

The example below creates an Access Grant for a single smart lock with a PIN code. To grant access to multiple doors at once, pass space_ids instead of device_ids. To target specific ACS entrances, use acs_entrance_ids. You can also request multiple modes in one call — for example, [{"mode": "code"}, {"mode": "mobile_key"}].

from seam import Seam

seam = Seam()

access_grant = seam.access_grants.create(
    user_identity={
        "full_name": "Jane Doe",
        "email_address": "jane@example.com",
    },
    device_ids=["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods=[{"mode": "code"}],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
)

import { Seam } from "seam";

const seam = new Seam();

const accessGrant = await seam.accessGrants.create({
  user_identity: {
    full_name: "Jane Doe",
    email_address: "jane@example.com",
  },
  device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
  requested_access_methods: [{ mode: "code" }],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z",
});

require "seam"

seam = Seam.new()

access_grant = seam.access_grants.create(
  user_identity: {
    full_name: "Jane Doe",
    email_address: "jane@example.com",
  },
  device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
  requested_access_methods: [{ "mode": "code" }],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z"
)

<?php
require 'vendor/autoload.php';

$seam = new Seam\SeamClient();

$access_grant = $seam->access_grants->create(
    user_identity: [
        "full_name" => "Jane Doe",
        "email_address" => "jane@example.com",
    ],
    device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods: [["mode" => "code"]],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
);

// Coming soon!

// Coming soon!

curl -X 'POST' \
  'https://connect.getseam.com/access_grants/create' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "user_identity": {
      "full_name": "Jane Doe",
      "email_address": "jane@example.com"
    },
    "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    "requested_access_methods": [{"mode": "code"}],
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z"
  }'

When you request mobile_key, Seam also generates an instant_key_url on the Access Grant — a shareable link that gives your user mobile access without downloading an app. See Using Instant Keys.

Requesting a Custom Access Code

By default, Seam generates a PIN code for each code access method. To request a specific code instead — for example, to reuse a code a guest already knows — include a code value alongside mode: "code" in requested_access_methods. The code must be 4–9 digits and contain only digits.

from seam import Seam

seam = Seam()

access_grant = seam.access_grants.create(
    user_identity={
        "full_name": "Jane Doe",
        "email_address": "jane@example.com",
    },
    device_ids=["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods=[{"mode": "code", "code": "1234"}],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
)

import { Seam } from "seam";

const seam = new Seam();

const accessGrant = await seam.accessGrants.create({
  user_identity: {
    full_name: "Jane Doe",
    email_address: "jane@example.com",
  },
  device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
  requested_access_methods: [{ mode: "code", code: "1234" }],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z",
});

require "seam"

seam = Seam.new()

access_grant = seam.access_grants.create(
  user_identity: {
    full_name: "Jane Doe",
    email_address: "jane@example.com",
  },
  device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
  requested_access_methods: [{ "mode": "code", "code": "1234" }],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z"
)

<?php
require 'vendor/autoload.php';

$seam = new Seam\SeamClient();

$access_grant = $seam->access_grants->create(
    user_identity: [
        "full_name" => "Jane Doe",
        "email_address" => "jane@example.com",
    ],
    device_ids: ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    requested_access_methods: [["mode" => "code", "code" => "1234"]],
    starts_at: "2025-07-13T15:00:00.000Z",
    ends_at: "2025-07-16T11:00:00.000Z"
);

// Coming soon!

// Coming soon!

curl -X 'POST' \
  'https://connect.getseam.com/access_grants/create' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "user_identity": {
      "full_name": "Jane Doe",
      "email_address": "jane@example.com"
    },
    "device_ids": ["6ba7b811-9dad-11d1-80b4-00c04fd430c8"],
    "requested_access_methods": [{"mode": "code", "code": "1234"}],
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z"
  }'

A requested code is a preference, not a guarantee. Seam applies it when it can and falls back to a generated code when it can’t:

The code is already in use on a device: Seam assigns a different code for that device and records a warning on the Access Grant (warning_code: "requested_code_unavailable") that includes both the original and the replacement code.
The grant spans multiple Salto locks: Seam ignores the requested code and assigns a single shared generated code across those devices, because Salto can’t guarantee the same PIN on every device.
The provider has stricter code-length limits: Some devices accept a narrower range than 4–9 digits. If the requested code isn’t valid for a device, Seam assigns a compatible code for that device instead.

Always read the resulting code back from the access method (see Step 2: Deliver the Access Methods) rather than assuming the requested value was used, and check the grant’s warning_map for any requested_code_unavailable warnings. For more on delivering and updating codes, see Using PIN Codes and Managing Access Methods.

Step 2: Deliver the Access Methods

After creating the grant, list the access methods to see what was created and check their issuance status.

access_methods = seam.access_methods.list(
    access_grant_id=access_grant.access_grant_id
)

for method in access_methods:
    print(f"{method.mode}: is_issued={method.is_issued}")

const accessMethods = await seam.accessMethods.list({
  access_grant_id: accessGrant.access_grant_id,
});

for (const method of accessMethods) {
  console.log(`${method.mode}: is_issued=${method.is_issued}`);
}

access_methods = seam.access_methods.list(
  access_grant_id: access_grant.access_grant_id
)

access_methods.each do |method|
  puts "#{method.mode}: is_issued=#{method.is_issued}"
end

$access_methods = $seam->access_methods->list(
    access_grant_id: $access_grant->access_grant_id
);

foreach ($access_methods as $method) {
    echo $method->mode . ": is_issued=" . $method->is_issued . "\n";
}

// Coming soon!

// Coming soon!

curl -X 'POST' \
  'https://connect.getseam.com/access_methods/list' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{\"access_grant_id\": \"${access_grant_id}\"}"

Each access method has an is_issued flag. Once it’s true, the credential is active and ready to deliver. How you deliver depends on the mode:

Mode	What to do	Guide
`code`	Read the `code` property and share the PIN with your user.	Using PIN Codes
`mobile_key`	Initialize the Seam mobile SDK with the `client_session_token`, or send the `instant_key_url`.	Using Mobile Keys / Instant Keys
`card`	Encode a fresh card or assign an existing card. `is_issued` becomes `true` after encoding or assignment.	Using Key Cards
`cloud_key`	Call `access_methods.unlock_door` from your web app to unlock on behalf of the user.	Using Cloud Keys

In a sandbox workspace, automatically-issued access methods are ready almost instantly. On real devices, issuance can take a few moments.

Tracking Issuance with Events

Instead of polling is_issued, you can listen for webhook events:

Event	Meaning
`access_method.issued`	The access method is ready to deliver.
`access_method.card_encoding_required`	A card needs to be encoded before it can be delivered.
`access_method.card_assignment_required`	A card needs to be assigned to a physical card before it can be issued.

Getting Started

Use Cases

Core Concepts

Capability Guides

UI Components

Developer Tools

Industry Guides

Device Manufacturer Guidance

Low-Level APIs

Creating an Access Grant

Before You Begin

Step 1: Create the Access Grant

Choosing Resources

Example

Requesting a Custom Access Code

Step 2: Deliver the Access Methods

Tracking Issuance with Events

​Before You Begin

​Step 1: Create the Access Grant

​Choosing Resources

​Example

​Requesting a Custom Access Code

​Step 2: Deliver the Access Methods

​Tracking Issuance with Events

Before You Begin

Step 1: Create the Access Grant

Choosing Resources

Example

Requesting a Custom Access Code

Step 2: Deliver the Access Methods

Tracking Issuance with Events