Quick Start

Add Lyra human verification to any website in under 5 minutes.

1. Register and get your keys

Register your site at https://lyraauth.com/api/auth/register to receive a site key (public, goes in your HTML) and a secret key (private, stays on your server).

POST /api/auth/register

{
  "domain": "yoursite.com",
  "email": "[email protected]"
}

Response:

{
  "site_key": "lyra_sk_abc123...",
  "secret_key": "lyra_secret_xyz..."
}

2. Add to your HTML form

<form action="/submit" method="POST">
  <!-- your existing form fields -->
  <input type="email" name="email" />

  <!-- add LyraAuth widget -->
  <div class="lyraauth"
       data-sitekey="YOUR_SITE_KEY"></div>

  <button type="submit">Submit</button>
</form>

<!-- load widget before closing body -->
<script src="https://lyraauth.com/widget.js" async></script>

Server-Side Verification

After form submission, verify the token on your backend before processing. Never trust client-side verification alone.

Python (requests)

import requests

def verify_human(token: str) -> bool:
  resp = requests.post(
    "https://lyraauth.com/api/auth/siteverify",
    data={
      "secret": "YOUR_SECRET_KEY",
      "token": token
    }
  )
  return resp.json().get("success", False)

Node.js (fetch)

async function verifyHuman(token) {
  const res = await fetch('https://lyraauth.com/api/auth/siteverify', {
    method: 'POST',
    body: new URLSearchParams({ secret: 'YOUR_SECRET_KEY', token })
  });
  const data = await res.json();
  return data.success;
}

React / Next.js

import { useEffect, useRef } from 'react';

export function LyraAuthWidget({ siteKey, onVerified }) {
  const ref = useRef();
  useEffect(() => {
    if (window.LyraAuth) {
      window.LyraAuth.render(ref.current, { siteKey, onSuccess: onVerified });
    }
  }, []);
  return <div ref={ref} />;
}

API Reference

GET /api/auth/challenge

Returns a new challenge for a site key.

Request

GET /api/auth/challenge?site_key=lyra_sk_abc123

Response

{
  "challenge_id": "ch_xyz...",
  "type": "sequence",
  "question": "What comes next: 2, 4, 8, ?",
  "options": ["12", "14", "16", "18"],
  "expires_at": "2026-03-28T12:05:00Z"
}

POST /api/auth/verify

Submit a challenge response and get a verification token.

POST /api/auth/siteverify

Server-to-server verification. Use your secret key to validate a token.

GET /api/auth/training/stats

View training data statistics for your site key.

GET /api/auth/training/export

Export your training data as JSONL (instruction / completion / preference format).

Note: Training data export requires a Pro or Enterprise account. Each record is quality-filtered: response time 500ms–60s, confidence ≥ 0.7.

VPS Deploy Guide

Self-host the full Lyra AI platform on any VPS. Recommended: DigitalOcean, Hetzner, or Linode ($6–12/month).

1. Provision your server

# Ubuntu 22.04 LTS recommended

apt update && apt upgrade -y
apt install -y python3.11 python3-pip git nginx certbot python3-certbot-nginx

2. Clone and install

git clone https://github.com/lyra-ai-platform/lyra /opt/lyra
cd /opt/lyra
pip install -r requirements.txt
python -m spacy download en_core_web_sm

3. Nginx configuration

# /etc/nginx/sites-available/lyraauth.com

server {
  server_name lyraauth.com www.lyraauth.com;
  location / {
    proxy_pass http://127.0.0.1:7860;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
  location /widget.js {
    alias /opt/lyra/lyra/authenticator/frontend/lyraauth.js;
  }
}

# Enable HTTPS with Let's Encrypt (free)

certbot --nginx -d lyraauth.com -d www.lyraauth.com

4. Systemd service

# /etc/systemd/system/lyra.service

[Unit]
Description=Lyra AI Platform
After=network.target

[Service]
User=lyra
WorkingDirectory=/opt/lyra
ExecStart=/usr/bin/python3 -m lyra.main
Restart=always
Environment=LYRA_HOST=127.0.0.1
Environment=LYRA_PORT=7860

[Install]
WantedBy=multi-user.target

# Enable and start

systemctl daemon-reload
systemctl enable lyra
systemctl start lyra
DNS: Point your domain's A record to your VPS IP address. HTTPS certificate from Let's Encrypt is free and auto-renews every 90 days.

COSHH AI

COSHH AI is Lyra's intelligent hazard assessment tool for UK Control of Substances Hazardous to Health compliance. It extracts data from Safety Data Sheets (SDS), performs AI-driven risk assessments, and generates compliance reports.

Key capabilities

  • Substance identification and CAS number lookup
  • Automated SDS extraction (PDF, image, plain text)
  • Exposure limit comparison against WEL/OEL databases
  • PPE recommendation engine
  • Compliance report generation (COSHH assessment form output)
  • Bulk processing for multi-substance environments

Availability

COSHH AI is currently in private beta. Request demo access at lyraauth.com/pages/coshh.html. API access will be available to enterprise customers on the Enterprise plan.

Sector focus: Manufacturing, laboratories, healthcare, and construction. COSHH AI is built to complement (not replace) qualified COSHH assessors.

WebSocket Chat

Lyra's chat API streams AI responses over a WebSocket connection. It is the same backend powering the dashboard chat UI.

Authentication

Pass your JWT token as a query parameter when opening the WebSocket.

Connect with auth token

const token = localStorage.getItem('lyra_token');
const convId = crypto.randomUUID();
const ws = new WebSocket(
  `wss://lyraauth.com/ws/${convId}?token=${token}`
);

Message protocol

Send a JSON message to start a response stream:

Send a message

ws.send(JSON.stringify({
  "message": "What is quantum entanglement?",
  "use_memory": true,
  "use_web_search": false
}));

The server streams back a sequence of typed events:

Event types received

{ "type": "start", "model": "Lyra-1" }
{ "type": "token", "content": "Quantum " }
{ "type": "token", "content": "entanglement..." }
{ "type": "done", "content": "<full response>" }

On error

{ "type": "error", "content": "<error message>" }

Full example (JavaScript)

const token = localStorage.getItem('lyra_token');
const convId = crypto.randomUUID();
const ws = new WebSocket(`wss://lyraauth.com/ws/${convId}?token=${token}`);
let reply = '';

ws.onopen = () => ws.send(JSON.stringify({
  message: 'Hello, Lyra!', use_memory: true
}));

ws.onmessage = ({ data }) => {
  const evt = JSON.parse(data);
  if (evt.type === 'token') reply += evt.content;
  if (evt.type === 'done') console.log('Reply:', reply);
  if (evt.type === 'error') console.error(evt.content);
};
Rate limits: Free tier — 100 messages/day per user. Pro — 5,000/day. Enterprise — unlimited. Memory and web search are available on all tiers.