Lockette API Documentation

Welcome to the Lockette API. Our API provides privacy-preserving age verification with a simple, RESTful interface. Verify users with a single API call while collecting zero personal information.

Authentication

All API requests require authentication using your API key. Include it in the request headers:

X-API-Key: your_api_key_here
Content-Type: application/json

Base URL

All API endpoints are accessed via:

All requests must be made over HTTPS. HTTP requests will be rejected.

Rate Limits

API rate limits are based on your subscription tier:

Rate limit headers are included in all responses:

• X-RateLimit-Limit - Maximum requests per window
• X-RateLimit-Remaining - Remaining requests in current window
• X-RateLimit-Reset - Unix timestamp when the window resets

Verify User

The primary endpoint for age verification. Returns a boolean indicating whether the user is verified.

Request Body

Example Request

const response = await fetch('https://api.lockette.dev/api/verify', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key'
    },
    body: JSON.stringify({
        instanceId: 'lk_inst_abc123xyz',
        restrictionLevel: '21+'
    })
});

const result = await response.json();

Response

{
    "verified": true,
    "restrictionLevel": "21+",
    "sessionActive": true,
    "expiresAt": "2025-01-15T12:00:00Z"
}

Check Status

Check the verification status of an instance without triggering a verification event.

Path Parameters

Response

{
    "instanceId": "lk_inst_abc123xyz",
    "state": "VERIFIED",
    "restrictionLevel": "21+",
    "sessionActive": true,
    "registeredAt": "2024-12-01T10:30:00Z",
    "sessionExpiresAt": "2025-01-15T12:00:00Z"
}

Health Check

Check API availability. No authentication required.

Response

{
    "status": "healthy",
    "version": "1.0.0",
    "timestamp": "2025-01-10T15:30:00Z"
}

Webhook Setup

Configure webhooks to receive real-time notifications when verification events occur.

Webhooks can be configured in the Customer Portal under Settings → Webhooks.

Webhook Events

Example Payload

{
    "id": "evt_123abc",
    "type": "verification.success",
    "timestamp": "2025-01-10T15:30:00Z",
    "data": {
        "instanceId": "lk_inst_abc123xyz",
        "restrictionLevel": "21+"
    }
}

Webhook Security

All webhook payloads are signed using HMAC-SHA256. Verify the signature to ensure the webhook is from Lockette:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from('sha256=' + expected)
    );
}

The signature is included in the X-Lockette-Signature header.

Error Codes

Error Response Format

{
    "error": {
        "code": "invalid_instance",
        "message": "The instance ID format is invalid",
        "details": "Instance ID must start with 'lk_inst_'"
    }
}

SDKs & Libraries

Official SDKs are coming soon. In the meantime, the API is fully accessible via standard HTTP requests.