Choose Your Integration Level

From zero-code embedding to full API control — pick the approach that matches your needs.

Level 1

Beginner

"Just embed it"

Copy-paste a URL or HTML snippet. No coding required.

HTML No-Code

Level 2

Hooks + UI Components

"Drop-in hooks, you render the UI"

Use useCheckinSession + dumb components like <KeyCard /> and <OtpLoginModal />. Business logic lives in hooks; UI is yours.

React Hooks TypeScript SDK

Level 3

Hooks Composition

"Compose your own flow"

Compose multiple hooks (useOtpAuth, usePlanSelection, useCheckinSession, useKeyRefresh) with your own JSX to build bespoke flows.

Custom Flow Compose Full Control

Level 4

Hardcore

"REST API all the way"

Call REST APIs directly. Build in any language — Python, Go, Ruby, etc.

REST API Any Language OpenAPI

Level 2: Hooks + UI Components

Wrap your app in <UnlockOSProvider>, then call useCheckinSession() — rendering is always up to you.

Installation

npm install @keyvox-org/unlockos-sdk

Quick Start

Coming soon in v0 GA Runnable sample code will be published with the v0 GA release.

Level 3: Hooks Composition

Compose multiple hooks with your own JSX. No stateful service class, no god object — just React.

SDK Architecture (5 Layers)

Layer 5: Dogfood apps (apps/member, apps/booking, apps/go)  @internal
          ↑
Layer 4: Dumb Components  <KeyCard /> <OtpInput /> <QrCodeDisplay />
          ↑
Layer 3: React Hooks      useCheckinSession, useKeyHub, useKeyRefresh, ...
          ↑
Layer 2: ❌ DOES NOT EXIST (no stateful service class — hooks compose flows directly)
          ↑
Layer 1: UnlockOSHttpClient   typed HTTP + retry + X-API-Key + idempotency
          ↑
Layer 0: Raw REST API     api.unlockos.io  (OpenAPI 3.1, 2527 lines)

Level 2 vs Level 3

Item	Level 2	Level 3
UI	SDK dumb components	Fully custom JSX
Authentication	<OtpLoginModal />	useOtpAuth + your UI
Plan selection	Skipped (single plan)	usePlanSelection + modal
Key display	<KeyCard />	Your component
Customization	Styling via tokens	Full freedom

Layer 3: Hooks (business logic)

`useCheckinSession`	Check-in/out, key issuance, restore
`useKeyHub`	Multi-key dashboard for one user
`useKeyRefresh`	Refresh expiring short-lived keys
`useCountdown`	Key expiration countdown timer

Layer 1: UnlockOSHttpClient

Typed HTTP client distributed via UnlockOSProvider. Auto-injects X-API-Key, idempotency keys, retry on 5xx. Access via useUnlockOSClient(). Does not compose flows — that's the hooks' job.

`apiKey`	Publishable key (ulk_pub_*)
`facilityId`	Facility scope for this key
`apiUrl`	Defaults to api.unlockos.io

Code Examples

Hooks Composition

Coming soon in v0 GA Runnable hooks composition samples will be published with the v0 GA release.

Level 4: REST API

Direct API calls for maximum flexibility. Works with any programming language.

Canonical /v1/* URL rewrite is planned. Until then, use the /functions/v1/* path below.

cURL

curl -X POST \
  https://api.unlockos.io/functions/v1/checkin-local \
  -H "Authorization: Bearer ulk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "guestEmail": "guest@example.com",
    "configId": "dflt-basic",
    "paymentMethod": "prepaid"
  }'

Python

import requests

response = requests.post(
    "https://api.unlockos.io/functions/v1/checkin-local",
    headers={
        "Authorization": f"Bearer {UNLOCKOS_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "guestEmail": "guest@example.com",
        "configId": "dflt-basic",
        "paymentMethod": "prepaid"
    }
)
data = response.json()
print(f"Check-in ID: {data['checkInId']}")

AI Agent Integration (MCP)

UnlockOS supports Model Context Protocol for AI-powered facility management.

View MCP API →

Ready to Get Started?

Choose your integration level and start building.

API Reference