Using Access Grants to Issue Instant Keys

An Access Grant defines the “who, where, when, and how” for assigning a user access to entrances, including the following characteristics:

Characteristic	Creation Parameter	Description
Who	`user_identity_id` or `user_identity`	The user to whom to grant access. You can either create a user identity separately and specify the ID to the access grant or create a new user identity as part of the Access Grant creation action.
Where	`acs_entrance_ids`	The entrances to which to grant access. You can specify one or more entrances by ID.
When	`starts_at` and `ends_at`	The access schedule.
How	`requested_access_methods` and `mode`	The access methods that you want to grant for the user. In each `requested_access_method`, specify the desired `mode` of access, such as a PIN code, key card, or mobile key (with an Instant Key).

Once you have identified the entrances to which you want to grant a user access, create an Access Grant to assign the specified access to the user. Specify mobile_key as the mode for a requested access method, and the resulting mobile key also includes an Instant Key. To create an Instant Key:

Identify the entrances to which you want to grant the user access.
Create a user identity for the user to whom you want to grant access. Alternately, you can create a new user identity as part of the Access Grant creation action.
Create an Access Grant for the user identity to define the entrances to which the user should have access, the starting and ending times for this access, and the requested access methods, including a mobile key.

The action returns an Access Grant that includes the Instant Key URL. You can then share this Instant Key URL with your user.

Identify Entrances

List the entrances in the access system and identify the ones to which you want to grant the user access.

Code

await seam.acs.entrances.list({
  acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339',
})

Output

[
  {
    "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
    "display_name": "Main Entrance",
    "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  },
  {
    "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc",
    "display_name": "Room 101",
    "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  },
  ...
]

Code

curl --include --request POST "https://connect.getseam.com/acs/entrances/list" \
  --header "Authorization: Bearer $SEAM_API_KEY" \
  --json @- <<EOF
{
  "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
}
EOF

Output

{
  "acs_entrances": [
    {
      "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "display_name": "Main Entrance",
      "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
      ...
    },
    {
      "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc",
      "display_name": "Room 101",
      "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
      ...
    },
    ...
  ]
}

Code

seam.acs.entrances.list(
  acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339"
)

Output

[
  AcsEntrance(
    acs_entrance_id="48ebfb50-c531-43c5-b9ea-409f26dabbd7",
    display_name="Main Entrance",
    acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  ),
  AcsEntrance(
    acs_entrance_id="f74e4879-5991-4e2f-a368-888983dcfbfc",
    display_name="Room 101",
    acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  ),
  ...
]

Code

seam.acs.entrances.list(
  acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
)

Output

[
  {
    "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
    "display_name" => "Main Entrance",
    "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  },
  {
    "acs_entrance_id" => "f74e4879-5991-4e2f-a368-888983dcfbfc",
    "display_name" => "Room 101",
    "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  },
  ...
]

Code

$seam->acs->entrances->list(
  acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
);

Output

[
  [
    "acs_entrance_id" => "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
    "display_name" => "Main Entrance",
    "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  ],
  [
    "acs_entrance_id" => "f74e4879-5991-4e2f-a368-888983dcfbfc",
    "display_name" => "Room 101",
    "acs_system_id" => "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  ],
  ...
];

Code

seam acs entrances list --acs_system_id "c359cba2-8ef2-47fc-bee0-1c7c2a886339"

Output

[
  {
    "acs_entrance_id": "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
    "display_name": "Main Entrance",
    "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  },
  {
    "acs_entrance_id": "f74e4879-5991-4e2f-a368-888983dcfbfc",
    "display_name": "Room 101",
    "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339",
    ...
  },
  ...
]

Create a User Identity

You can create a user identity before creating the Access Grant, you can retrieve an existing user identity, or you can skip this step and create a new user identity as part of the Access Grant creation action. To create a user identity, specify the unique user_identity_key, email_address, or phone_number of the user. Also, include the ID of the access system in which you want to grant the user access.

Code

await seam.userIdentities.create({
  full_name: 'Jane Doe',
  email_address: 'jane@example.com',
  acs_system_ids: ['c359cba2-8ef2-47fc-bee0-1c7c2a886339'],
})

Output

{
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "full_name": "Jane Doe",
  "email_address": "jane@example.com",
  ...
}

Code

curl --include --request POST "https://connect.getseam.com/user_identities/create" \
  --header "Authorization: Bearer $SEAM_API_KEY" \
  --json @- <<EOF
{
  "full_name": "Jane Doe",
  "email_address": "jane@example.com",
  "acs_system_ids": [
    "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
  ]
}
EOF

Output

{
  "user_identity": {
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    ...
  }
}

Code

seam.user_identities.create(
  full_name="Jane Doe",
  email_address="jane@example.com",
  acs_system_ids=["c359cba2-8ef2-47fc-bee0-1c7c2a886339"]
)

Output

UserIdentity(
  user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
  full_name="Jane Doe",
  email_address="jane@example.com",
  ...
)

Code

seam.user_identities.create(
  full_name: "Jane Doe",
  email_address: "jane@example.com",
  acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"],
)

Output

{
  "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "full_name" => "Jane Doe",
  "email_address" => "jane@example.com",
  ...
}

Code

$seam->user_identities->create(
  full_name: "Jane Doe",
  email_address: "jane@example.com",
  acs_system_ids: ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"]
);

Output

[
  "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "full_name" => "Jane Doe",
  "email_address" => "jane@example.com",
  ...
];

Code

seam user-identities create --email_address "jane@example.com" --full_name "Jane Doe" --acs_system_ids ["c359cba2-8ef2-47fc-bee0-1c7c2a886339"]

Output

{
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "full_name": "Jane Doe",
  "email_address": "jane@example.com",
  ...
}

Create an Access Grant

To create an Access Grant, specify the user identity, entrance IDs, starting and ending times, and requested access methods. To issue an Instant Key, specify mobile_key as the mode for a requested access method.

Code

await seam.accessGrants.create({
  user_identity_id: 'e3d736c1-540d-4d10-83e5-9a4e135453b4',
  // Alternately, to create a new user identity, use the
  // following parameter instead of user_identity_id:
  // user_identity: {
  //  full_name: "Jane Doe",
  //  email_address: "jane.doe@example.com",
  // },
  acs_entrance_ids: [
    '48ebfb50-c531-43c5-b9ea-409f26dabbd7',
    'f74e4879-5991-4e2f-a368-888983dcfbfc',
  ],
  requested_access_methods: [{ mode: 'mobile_key' }],
  starts_at: '2025-07-13T15:00:00.000Z',
  ends_at: '2025-07-16T11:00:00.000Z',
})

Output

{
  "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
  "display_name": "My Access Grant",
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "starts_at": "2025-07-13T15:00:00.000Z",
  "ends_at": "2025-07-16T11:00:00.000Z",
  "requested_access_methods": [
    {
      "display_name": "Mobile Key Credential",
      "mode": "mobile_key",
      "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
      ...
    }
  ],
  "instant_key_url": "https://ik.seam.co/THSDKS",
  ...
}

Code

# Alternately, to create a new user identity, use the
# following parameter instead of user_identity_id:
# user_identity={
#  "full_name": "Jane Doe",
#  "email_address": "jane.doe@example.com",
# },
curl --include --request POST "https://connect.getseam.com/access_grants/create" \
  --header "Authorization: Bearer $SEAM_API_KEY" \
  --json @- <<EOF
{
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "acs_entrance_ids": [
    "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
    "f74e4879-5991-4e2f-a368-888983dcfbfc"
  ],
  "requested_access_methods": [
    {
      "mode": "mobile_key"
    }
  ],
  "starts_at": "2025-07-13T15:00:00.000Z",
  "ends_at": "2025-07-16T11:00:00.000Z"
}
EOF

Output

{
  "access_grant": {
    "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
    "display_name": "My Access Grant",
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "starts_at": "2025-07-13T15:00:00.000Z",
    "ends_at": "2025-07-16T11:00:00.000Z",
    "requested_access_methods": [
      {
        "display_name": "Mobile Key Credential",
        "mode": "mobile_key",
        "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
        ...
      }
    ],
    "instant_key_url": "https://ik.seam.co/THSDKS",
    ...
  }
}

Code

seam.access_grants.create(
  user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
  # Alternately, to create a new user identity, use the
  # following parameter instead of user_identity_id:
  # user_identity={
  #  "full_name": "Jane Doe",
  #  "email_address": "jane.doe@example.com",
  # },
  acs_entrance_ids=[
    "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
    "f74e4879-5991-4e2f-a368-888983dcfbfc"
  ],
  requested_access_methods=[
    {"mode": "mobile_key"}
  ],
  starts_at="2025-07-13T15:00:00.000Z",
  ends_at="2025-07-16T11:00:00.000Z"
)

Output

AccessGrant(
  access_grant_id="ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
  display_name="My Access Grant",
  user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b",
  starts_at="2025-07-13T15:00:00.000Z",
  ends_at="2025-07-16T11:00:00.000Z"
  requested_access_methods=[
    {
      "display_name": "Mobile Key Credential",
      "mode": "mobile_key",
      "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
      ...
    },
  ],
  instant_key_url="https://ik.seam.co/THSDKS",
  ...
)

Code

seam.access_grants.create(
  user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4",
  # Alternately, to create a new user identity, use the
  # following parameter instead of user_identity_id:
  # user_identity: {
  #  full_name: "Jane Doe",
  #  email_address: "jane.doe@example.com",
  # },
  acs_entrance_ids: %w[48ebfb50-c531-43c5-b9ea-409f26dabbd7 f74e4879-5991-4e2f-a368-888983dcfbfc],
  requested_access_methods: [{ mode: "mobile_key" }],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z"
)

Output

{
  "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
  "display_name" => "My Access Grant",
  "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "starts_at" => "2025-07-13T15:00:00.000Z",
  "ends_at" => "2025-07-16T11:00:00.000Z",
  "requested_access_methods" => [
    {
      "display_name": "Mobile Key Credential",
      "mode": "mobile_key",
      "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
      ...
    }
  ],
  "instant_key_url" => "https://ik.seam.co/THSDKS",
  ...
}

Code

$seam->access_grants->create(
  user_identity_id: "e3d736c1-540d-4d10-83e5-9a4e135453b4",
  // Alternately, to create a new user identity, use the
  // following parameter instead of user_identity_id:
  // user_identity: {
  //  full_name: "Jane Doe",
  //  email_address: "jane.doe@example.com",
  // },
  acs_entrance_ids: [
      "48ebfb50-c531-43c5-b9ea-409f26dabbd7",
      "f74e4879-5991-4e2f-a368-888983dcfbfc",
  ],
  requested_access_methods: [
      ["mode" => "mobile_key"],
  ],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z"
);

Output

[
  "access_grant_id" => "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
  "display_name" => "My Access Grant",
  "user_identity_id" => "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "starts_at" => "2025-07-13T15:00:00.000Z",
  "ends_at" => "2025-07-16T11:00:00.000Z",
  "requested_access_methods" => [
    [
      "display_name" => "Mobile Key Credential",
      "mode" => "mobile_key",
      "created_access_method_ids" => [
          "c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      ],
    ],
  ],
  "instant_key_url" => "https://ik.seam.co/THSDKS",
  ...
];

Code

seam access-grants create --user_identity_id "e3d736c1-540d-4d10-83e5-9a4e135453b4" --acs_entrance_ids ["48ebfb50-c531-43c5-b9ea-409f26dabbd7","f74e4879-5991-4e2f-a368-888983dcfbfc"] --requested_access_methods [{"mode":"mobile_key"}] --starts_at "2025-07-13T15:00:00.000Z" --ends_at "2025-07-16T11:00:00.000Z"

Output

{
  "access_grant_id": "ef83cca9-5fdf-4ac2-93f3-c21c5a8be54b",
  "display_name": "My Access Grant",
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "starts_at": "2025-07-13T15:00:00.000Z",
  "ends_at": "2025-07-16T11:00:00.000Z",
  "requested_access_methods": [
    {
      "display_name": "Mobile Key Credential",
      "mode": "mobile_key",
      "created_access_method_ids": ["c7d8e9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
      ...
    }
  ],
  "instant_key_url": "https://ik.seam.co/THSDKS",
  ...
}

Within the response, the instant_key_url property provides the issued Instant Key. Share this URL with your user. For details, see Delivering Instant Keys.

​Identify Entrances

​Create a User Identity

​Create an Access Grant

Identify Entrances

Create a User Identity

Create an Access Grant