Granting Access Using Mobile Keys

To issue mobile keys, first identify the user to whom you want to grant access and create a user identity to represent this user. Then, create an Access Grant to specify the entrances and spaces to which you want to grant the user access. Through this Access Grant, Seam generates all the necessary mobile keys. You can then deliver the mobile keys to your user in a mobile app that you develop. Your user installs this app on their phone.

Seam also provides Instant Keys as an app-free alternative to mobile keys. When you create a mobile key, Seam automatically also creates an Instant Key.

This section details the steps in this process and provides accompanying Seam API code samples. See the following instructions:

1. Create a User Identity

2. Create an Access Grant

3. Deliver the Mobile Key

---

Create a User Identity

On the server side, use the Seam API to create a user_identity. A user identity represents the hotel guest, that is, your mobile app user.

Python

Code:

# Create a user identity for your mobile app user.
jane_user = seam.user_identities.create(
  full_name = "Jane Doe",
  phone_number = "[phone]"
)

Output:

UserIdentity(
  user_identity_id='43947360-cdc8-4db6-8b22-e079416d1d8b',
  full_name='Jane Doe',
  phone_number='[phone]',
  ...
)

cURL (bash)

Code:

# Create a user identity for your mobile app user.
jane_user=$(curl -X 'POST' \
  'https://connect.getseam.com/user_identities/create' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "full_name": "Jane Doe",
  "phone_number": "[phone]"
}')

Output:

{
  "user_identity": {
    "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
    "full_name": "Jane Doe",
    "phone_number": "[phone]",
    ...
  },
  "ok": true
}

JavaScript

Code:

// Create a user identity for your mobile app user.
const janeUser = await seam.userIdentities.create({
  full_name: "Jane Doe",
  phone_number: "[phone]"
});

Output:

{
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "full_name": "Jane Doe",
  "phone_number": "[phone]",
  ...
}

Ruby

Code:

# Create a user identity for your mobile app user.
jane_user = seam.user_identities.create(
  full_name: "Jane Doe",
  phone_number: "[phone]"
)

Output:

<Seam::Resources::UserIdentity:0x005f0
  user_identity_id="43947360-cdc8-4db6-8b22-e079416d1d8b"
  full_name="Jane Doe"
  phone_number="[phone]"
  ...
>

PHP

Code:

// Create a user identity for your mobile app user.
$jane_user = $seam->user_identities->create(
  full_name: "Jane Doe",
  phone_number: "[phone]"
);

Output:

{
  "user_identity_id": "43947360-cdc8-4db6-8b22-e079416d1d8b",
  "full_name": "Jane Doe",
  "phone_number": "[phone]",
  ...
}

C#

Code:

// Coming soon!

Output:

// Coming soon!

---

Create an Access Grant

To create an Access Grant, specify the user identity, entrance or space IDs, and starting and ending times. Include mobile_key as a requested access method.

Python

Code:

seam.access_grants.create(
  # You can specify the ID of an existing user identity or
  # use the user_identity parameter to create a new one.
  user_identity_id=jane_user.user_identity_id,
  # You can specify acs_entrance_ids, space_ids, or both.
  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",
      "mode": "mobile_key",
      "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
      ...
    }
  ],
  instant_key_url="https://ik.seam.co/ABCXYZ",
  ...
)

cURL (bash)

Code:

# You can specify the ID of an existing user identity or
# use the user_identity parameter to create a new one.
# Also, you can specify acs_entrance_ids, space_ids, or both.
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_id\": \"$(jq -r '.user_identity.user_identity_id' <<< ${jane_user})\"
    \"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": {
    "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",
        "mode": "mobile_key",
        "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
        ...
      }
    ],
    "instant_key_url": "https://ik.seam.co/ABCXYZ",
    ...
  }
}

JavaScript

Code:

await seam.accessGrants.create({
  // You can specify the ID of an existing user identity or
  // use the user_identity parameter to create a new one.
  user_identity_id: janeUser.user_identity_id,
  // You can specify acs_entrance_ids, space_ids, or both.
  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",
      "mode": "mobile_key",
      "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
      ...
    }
  ],
  "instant_key_url": "https://ik.seam.co/ABCXYZ",
  ...
}

Ruby

Code:

seam.access_grants.create(
  # You can specify the ID of an existing user identity or
  # use the user_identity parameter to create a new one.
  user_identity_id: jane_user.user_identity_id,
  # You can specify acs_entrance_ids, space_ids, or both.
  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",
      "mode": "mobile_key",
      "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
      ...
    }
  ],
  "instant_key_url" => "https://ik.seam.co/ABCXYZ",
  ...
}

PHP

Code:

$seam->access_grants->create(
  // You can specify the ID of an existing user identity or
  // use the user_identity parameter to create a new one.
  user_identity_id: $jane_user->user_identity_id,
  // You can specify acs_entrance_ids, space_ids, or both.
  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",
      "mode": "mobile_key",
      "created_access_method_ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"],
      ...
    }
  ],
  "instant_key_url" => "https://ik.seam.co/ABCXYZ",
  ...
];

C#

Code:

// Coming Soon!

Output:

// Coming Soon!

---

Deliver the Mobile Key

Seam provides a mobile SDK for iOS and Android that you can use to develop a mobile key app. Your user installs your mobile app and logs in. To use mobile keys, your user must enable certain phone functions—such as Bluetooth—and give your app permission to use these functions. Then, your mobile app downloads the user's mobile key credentials and presents them to your user.

The Seam mobile SDK uses a scanning model called "unlock with tap" to unlock the nearest granted entrance. Your app starts this scanning process, your user holds their mobile device up to the hotel room door or other access point, and it unlocks.

Develop a mobile app to deliver the mobile key to your user and to unlock the door.

Alternately, for a more streamlined experience that does not require an app download, use Seam Instant Keys.