Core Concepts

Passwave organizes access control around four core entities that work together to provide comprehensive access management. Understanding these concepts is essential before building your integration.

Properties

A property represents a physical location managed through Passwave—a hotel, apartment building, residential community, or office space. Each property is independent and isolated, allowing you to manage multiple locations through a single API.

Properties have a type indicating their primary use case. hotel properties optimize for short-term guest access with automatic expiration. residential properties serve permanent residents with occasional guests. multifamily properties manage multiple buildings. commercial properties handle office or workspace access.

Each property associates with an OEM provider indicating which manufacturer's systems are installed: Salto, Yale, ASSA ABLOY, Dormakaba, or custom integrations. This tells Passwave which protocols to use when provisioning credentials.

{
  "id": "prop_123",
  "name": "Grand Hotel Downtown",
  "type": "hotel",
  "oem_provider": "salto",
  "timezone": "America/New_York"
}

Devices

Devices are the physical access systems installed at properties. They're the actual decision point—when a guest presents a credential, the device validates it and grants or denies access.

Each device type supports different capabilities. A smart lock might support BLE (Bluetooth wireless), NFC (card reading), and pincode entry. A turnstile might support mobile credentials and cards only. When registering a device, you specify its capabilities, which determines which credential types work with it.

Every device has a Passwave-assigned device_id and an oem_device_id identifying it in the manufacturer's system. Passwave maps between these namespaces to translate your API requests into manufacturer-specific commands. The status field indicates whether the device is online, offline, or in error state.

{
  "id": "dev_456",
  "property_id": "prop_123",
  "device_type": "smart_lock",
  "location": "Room 301",
  "oem_device_id": "salto_lock_301",
  "capabilities": ["ble", "nfc", "pincode"],
  "status": "online"
}

Credentials

Credentials are access artifacts issued to users. They represent authorization to access specific areas during specific time periods. Credentials decouple user experience from device technology—you don't need to know whether a device uses BLE or NFC; Passwave translates your credential into the appropriate format.

Passwave supports multiple credential types: digital_wallet credentials appear in Apple Wallet or Google Wallet, ble_pincode credentials are numeric codes for keypads, temporary_pass credentials are short-lived, permanent_pass credentials have no expiration.

Every credential has a status indicating its lifecycle state: pending (not yet active), active (usable), suspended (temporarily disabled), revoked (permanently disabled), or expired (passed its valid_until date).

Credentials contain valid_from (when they activate, optional) and valid_until (when they stop working, required) timestamps. For hotel guests, valid_until is checkout time. For residents, it might be a year in the future.

{
  "id": "cred_789",
  "property_id": "prop_123",
  "user_identifier": "guest@example.com",
  "credential_type": "digital_wallet",
  "status": "active",
  "access_points": ["Room 301"],
  "valid_until": "2025-01-21T11:00:00Z"
}

Access Rules

Access rules connect credentials to devices and define the terms of access. A rule specifies which credential can access which device, under what conditions, and during what time period.

Rules define an access_level: entry allows opening a door, exit permits leaving, admin grants administrative capabilities. Most use cases need only entry.

Rules can have fixed time windows (valid_from to valid_until) for specific time-bound access, or be schedule-based (Monday 6 AM to Friday 8 PM) for recurring patterns. The key insight: rules expire automatically. When valid_until passes, Passwave denies access. You don't manually revoke credentials at checkout—time-based expiration handles it automatically.

Credential Lifecycle

Every credential follows a predictable lifecycle:

Created — You call the create credential endpoint. The credential enters pending status and cannot yet grant access.

Activated — The credential transitions to active status and can be used for access. If you specified a future valid_from date, this happens automatically at that time. Otherwise, it activates immediately.

Used — When a user presents the credential to a device, Passwave records an access event (granted or denied).

Suspended (optional) — You can temporarily suspend a credential without revoking it. Suspended credentials deny access but can be reactivated later.

Revoked or Expired — Either you explicitly revoke it (permanent, irreversible) or it automatically expires when valid_until passes (credentials reaching expired status).

Events

Every significant event generates an event record: credential creation, update, revocation, access attempt. These events flow to your application in real-time through webhooks, allowing you to build audit trails, trigger notifications, or detect security issues.

All events are retained in Passwave's audit log for historical querying by date, event type, property, device, or credential.