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

Light Developer

"UI included, I control the flow"

Use CheckinServiceWithUI — auth, payment, and key display modals with minimal code.

TypeScript React SDK

Level 3

Core Developer

"My UI, your logic"

Build your own UI, use SDK services for business logic. Full control over UX.

TypeScript Custom UI Ports

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: CheckinServiceWithUI

The fastest way to integrate UnlockOS with a polished UI experience.

Installation

npm install @keyvox-org/unlockos-sdk

Quick Start

import { CheckinServiceWithUI } from '@keyvox-org/unlockos-sdk';

const service = new CheckinServiceWithUI();
service.setModalManager(modalManager);

// One line handles auth → payment → key display
const result = await service.checkin({
  configId: 'your-config-id',
  guestEmail: 'guest@example.com'
});

if (result.success) {
  console.log('Check-in ID:', result.stay.id);
}

Level 3: Core SDK Services

Use SDK services with your own custom UI components.

SDK Architecture

┌─────────────────────────────────┐
│      Your Code (Level 3)        │
│    Custom UI Components         │
└───────────────┬─────────────────┘
                ↓
┌─────────────────────────────────┐
│          Services               │
│  CheckinService, CheckoutService│
│  PaymentService, OccupancyService│
└───────────────┬─────────────────┘
                ↓
┌─────────────────────────────────┐
│          MicroAPIs              │
│  CheckinApi, FeeApi, KeyApi     │
│  PaymentApi, ReservationApi     │
└───────────────┬─────────────────┘
                ↓
┌─────────────────────────────────┐
│    Supabase Edge Functions      │
└─────────────────────────────────┘

Level 2 vs Level 3

Item	Level 2	Level 3
UI	SDK modals	Custom implementation
Authentication	Automatic	Your control
Payment	Auto display	Your display
Key display	Auto display	Your display
Customization	Limited	Full freedom

Services (Business Logic)

`CheckinService`	Check-in flow
`CheckoutService`	Checkout flow
`PaymentService`	Payment processing
`OccupancyService`	Occupancy tracking

MicroAPIs (Direct Calls)

`CheckinApi`	Create check-in
`FeeApi`	Calculate fees
`KeyApi`	Issue lock keys
`PaymentApi`	Process payments
`ReservationApi`	Manage reservations

Code Examples

Basic Workflow

import { CheckinService, CheckoutService } from '@keyvox-org/unlockos-sdk';

const checkinService = new CheckinService();
const checkoutService = new CheckoutService();

// Check-in
const result = await checkinService.checkin({
  guestEmail: 'guest@example.com',
  configId: 'config-id',
  paymentMethod: 'prepaid'
});

// Handle result with YOUR custom UI
if (result.nextAction === 'payment_required') {
  showMyPaymentForm(result.payment);
} else if (result.entryKey) {
  showMyKeyDisplay(result.entryKey);
}

// Checkout
await checkoutService.checkout({
  checkInId: result.checkInId
});

MicroAPI Direct Use

import { FeeApi, KeyApi } from '@keyvox-org/unlockos-sdk';

// Fee calculation only
const feeApi = new FeeApi();
const fee = await feeApi.calculateFee({
  pricePlanId: 'plan-001',
  startDateTime: '2024-12-01T10:00:00Z',
  endDateTime: '2024-12-01T12:00:00Z'
});

console.log('Total:', fee.finalDisplayFee);

// Key issuance only
const keyApi = new KeyApi();
const key = await keyApi.createLockPin(
  unitId,
  'Guest Name'
);

Custom Port Implementation

import {
  KeyPort,
  CheckinService
} from '@keyvox-org/unlockos-sdk';

// Custom lock provider
class MyLockProvider implements KeyPort {
  async createLockPin(unitId, name) {
    // Call your own lock API
    return await myLockApi.createKey({
      unitId,
      name
    });
  }
}

// Inject custom port
const service = new CheckinService({
  key: new MyLockProvider()
});

Level 4: REST API

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

cURL

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

Python

import requests

response = requests.post(
    f"{SUPABASE_URL}/functions/v1/checkin-local",
    headers={
        "Authorization": f"Bearer {jwt_token}",
        "apikey": anon_key
    },
    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 GitHub