Skip to main content

​
Overview

The Device Enrollment Edge Function manages the complete device lifecycle: generating enrollment tokens, validating devices, and integrating with Tailscale for network access. Endpoint: /functions/v1/device-enrollment Authentication: Required (Authorization header with Supabase JWT)

​
Actions

​
Create Pending Device

Admin action to create a pending device for a user with pre-configured Tailscale auth key. Action: create_pending_device
​
user_id
string
Target user ID (defaults to authenticated user)
​
organization_id
string
Organization ID
​
device_name
string
Device name (defaults to “Pending Device”)
​
device_type
string
Device type: laptop, desktop, mobile, tablet, windows, macos
​
os
string
Operating system (max 50 chars)
​
tailscale_auth_key
string
Optional Tailscale auth key (uses org config if not provided)
​
success
boolean
Whether device was created
​
device_id
string
UUID of created device
​
enrollment_token
string
Token for device enrollment (share with user)
​
expires_at
string
Token expiration timestamp (24 hours)
Example Request
curl -X POST 'https://your-project.supabase.co/functions/v1/device-enrollment' \
  -H 'Authorization: Bearer YOUR_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "create_pending_device",
    "user_id": "uuid-of-user",
    "organization_id": "uuid-of-org",
    "device_name": "MacBook Pro",
    "device_type": "laptop",
    "os": "macOS 14.0"
  }'

​
Generate Token

User-initiated action to generate an enrollment token for their new device. Action: generate_token
​
device_name
string
Device name (defaults to “New Device”)
​
device_type
string
Device type (defaults to “laptop”)
​
os
string
Operating system
​
success
boolean
Whether token was generated
​
enrollment_token
string
Enrollment token (UUID format)
​
device_id
string
Created device ID
​
expires_at
string
Token expiration (24 hours from now)
​
has_tailscale_key
boolean
Whether Tailscale auth key is configured

​
Enroll Device

Silent enrollment when device provides its fingerprint. Action: enroll
​
fingerprint
string
required
Unique device fingerprint (alphanumeric with hyphens, max 100 chars)
​
device_name
string
Device name
​
device_type
string
Device type
​
os
string
Operating system
​
success
boolean
Enrollment success status
​
device_id
string
Device ID (existing or newly created)
​
status
string
Device status: active or existing status
​
message
string
Result message
Example Request
curl -X POST 'https://your-project.supabase.co/functions/v1/device-enrollment' \
  -H 'Authorization: Bearer YOUR_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "enroll",
    "fingerprint": "abc123-def456-ghi789",
    "device_name": "My MacBook",
    "device_type": "laptop",
    "os": "macOS 14.0"
  }'

​
Verify Token

Validates an enrollment token and returns Tailscale configuration. Action: verify
​
enrollment_token
string
required
Enrollment token from generate_token or create_pending_device
​
device_type
string
Device type to update
​
fingerprint
string
Device fingerprint
​
success
boolean
Validation success
​
device_id
string
Device ID
​
device_name
string
Device name from registration
​
organization_name
string
Organization name
​
tailscale_auth_key
string
Tailscale authentication key for device setup
​
tailscale_tags
string[]
Tailscale tags to apply (e.g., ["tag:prod"])
​
tailscale_group
string
Tailscale ACL group
​
expires_at
string
Token expiration timestamp
Example Request
curl -X POST 'https://your-project.supabase.co/functions/v1/device-enrollment' \
  -H 'Authorization: Bearer YOUR_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "verify",
    "enrollment_token": "uuid-token-here",
    "device_type": "laptop",
    "fingerprint": "device-fingerprint"
  }'

​
Check Tailscale Status

Checks if a device has successfully connected to Tailscale network. Action: check_tailscale_status
​
enrollment_token
string
required
Device ID (passed via this field for compatibility)
​
success
boolean
Request success
​
status
string
Device status
​
tailscale_connected
boolean
Whether device is connected to Tailscale
​
tailscale_hostname
string
Tailscale hostname (if connected)
​
tailscale_ip
string
Tailscale IP address (if connected)

​
Input Validation

​
Device Name

  • Type: String
  • Length: 1-100 characters
  • Required for most actions

​
Device Type

  • Type: String
  • Allowed values: laptop, desktop, mobile, tablet, windows, macos
  • Validates against whitelist

​
Operating System

  • Type: String
  • Length: 1-50 characters

​
Fingerprint

  • Type: String
  • Pattern: Alphanumeric with hyphens ([a-zA-Z0-9-]+)
  • Length: Max 100 characters
  • Must be unique per user

​
TypeScript Interfaces

TypeScript
interface EnrollmentPayload {
  action: 'generate_token' | 'enroll' | 'verify' | 'create_pending_device' | 'check_tailscale_status'
  device_name?: string
  device_type?: string
  os?: string
  fingerprint?: string
  enrollment_token?: string
  user_id?: string
  organization_id?: string
  tailscale_auth_key?: string
}

​
Device Statuses

  • pending - Device created but not enrolled
  • active - Device enrolled and active
  • inactive - Device deactivated
  • revoked - Device access revoked

​
Trust Levels

  • low - Default for pending devices
  • medium - Silent enrollment without Tailscale
  • high - Enrolled with Tailscale verification

​
Audit Events

All actions are logged to device_events and audit_logs tables:
  • pending_device_created
  • enrollment_initiated
  • enrolled
  • token_validated
  • tailscale_connected

​
Error Responses

​
error
string
Error message
Common errors:
  • Authorization header required - Missing auth
  • Invalid device name - Name validation failed
  • Invalid device type - Type not in allowed list
  • Token inválido o expirado - Invalid or expired token
  • No Tailscale auth key configured - Missing Tailscale config
  • devices - Device records
  • device_events - Device activity log
  • organization_tailscale_config - Tailscale configuration per org

Build docs developers (and LLMs) love

Get started for freeTalk to us