Seam Access Grants

Seam Access Grants

You are an expert Seam integration engineer. Write the integration code directly into the developer's existing codebase.

Approach

1. Move fast. Glob for key files (booking/reservation handlers, routes, models), read them, start writing code.
2. Write code in existing files. Add Seam calls directly into existing service/handler functions. Don't create wrapper services.
3. Minimize changes. Only touch files that need Seam calls + webhook route. Install SDK, add import, add calls.

How Access Grants works

You create an access grant specifying a user identity, target devices, requested access methods (PIN, mobile key), and a time window. Seam provisions the credentials on the locks. You must store the access_grant_id to update or delete it later.

1. Install SDK + initialize

Do NOT pin to a specific version.

npm install seam        # Node.js
pip install seam        # Python
bundle add seam         # Ruby

CRITICAL for Next.js: new Seam() at module scope BREAKS next build. Use a lazy getter:

import { Seam } from "seam";
let _seam: Seam;
function getSeam() {
  if (!_seam) _seam = new Seam({ apiKey: process.env.SEAM_API_KEY! });
  return _seam;
}

For Express / standard Node.js:

import { Seam } from "seam";
const seam = new Seam({ apiKey: process.env.SEAM_API_KEY });

from seam import Seam
seam = Seam(api_key=os.environ["SEAM_API_KEY"])

2. Get the device ID

Access Grants targets specific devices by device_id. Each room/door must map to its own device ID — never use a single global device for all rooms.

Look for device IDs in:

• Environment variables per room: SEAM_DEVICE_ROOM_101, SEAM_DEVICE_ID_ROOM_A1, etc.
• The app's data model (e.g., room.seamDeviceId, unit.deviceId)

If the mapping is missing, fail the operation — do not fall back to a global device. Granting access to the wrong door is worse than failing.

3. Create access grant on booking creation

Add directly inside the create function. Store the access_grant_id on the booking object.

// Inside createBooking(), after saving the booking:
const deviceId = getDeviceIdForRoom(room);  // Must resolve per-room
if (!deviceId) {
  throw new Error(`No Seam device configured for room ${room.id}`);
}
try {
  const accessGrant = await seam.accessGrants.create({
    user_identity: {
      full_name: guest.name,
      email_address: guest.email
    },
    device_ids: [deviceId],
    requested_access_methods: [
      { mode: "code" }           // PIN code
      // { mode: "mobile_key" }  // Add for mobile key + Instant Key
    ],
    starts_at: booking.checkIn,
    ends_at: booking.checkOut
  });
  booking.seamAccessGrantId = accessGrant.access_grant_id;
} catch (err) {
  console.error("Seam access grant failed:", err);
  // Consider: should this fail the booking? If access is required, throw.
}

# Inside create_booking(), after saving:
device_id = get_device_id_for_room(room)  # Must resolve per-room
if not device_id:
    raise ValueError(f"No Seam device configured for room {room.id}")
try:
    access_grant = seam.access_grants.create(
        user_identity={"full_name": guest.name, "email_address": guest.email},
        device_ids=[device_id],
        requested_access_methods=[{"mode": "code"}],
        starts_at=booking.check_in,
        ends_at=booking.check_out
    )
    booking.seam_access_grant_id = access_grant.access_grant_id
except Exception as e:
    print(f"Seam access grant failed: {e}")
    # Consider: should this fail the booking? If access is required, raise.

Gotchas

• Store access_grant_id — you need it for update and delete. Add a field to the booking model if one doesn't exist. If it's null/undefined, the grant failed and needs retry.
• Never use a global device fallback — each room must map to its specific device. Wrong-room access is worse than no access.
• user_identity takes full_name and email_address, NOT name and email.
• device_ids is an array — you can grant access to multiple doors in one call.
• requested_access_methods — "code" for PIN, "mobile_key" for mobile key + Instant Key.
• Decide your failure mode: if access is required for the booking (e.g., hotel room), throw on Seam failure so the booking doesn't confirm without a working code. If access is optional (e.g., gym), log and continue.

4. Update access grant on booking changes

if (booking.seamAccessGrantId) {
  await seam.accessGrants.update({
    access_grant_id: booking.seamAccessGrantId,
    starts_at: booking.checkIn,
    ends_at: booking.checkOut
  });
}

5. Delete access grant on cancellation

if (booking.seamAccessGrantId) {
  await seam.accessGrants.delete({
    access_grant_id: booking.seamAccessGrantId
  });
}

if booking.seam_access_grant_id:
    seam.access_grants.delete(
        access_grant_id=booking.seam_access_grant_id
    )

6. Add webhook endpoint

Follow the existing webhook pattern in the codebase:

router.post("/seam", (req, res) => {
  const { event_type, ...data } = req.body;
  switch (event_type) {
    case "access_code.set_on_device":
      console.log("PIN set on lock:", data.access_code_id);
      break;
    case "access_code.failed_to_set_on_device":
      console.log("PIN failed:", data.access_code_id);
      break;
    case "device.disconnected":
      console.log("Lock offline:", data.device_id);
      break;
  }
  res.json({ received: true });
});

7. Make functions async

Make service functions async and update callers to await them.

If something goes wrong, read references/troubleshooting.md. For production readiness, read references/production-checklist.md.