Authentication

​

Quick summary

​

Option A — API secret authentication

​

Setup steps

1. Generate a long random secret.
   Copy

   openssl rand -base64 32
   
2. Set the environment variables:
   Copy

   AUTH_REQUIRED=true
   AUTH_API_SECRET=your-generated-secret
   
3. Clients send the secret as a bearer token:
   Copy

   curl -X POST http://localhost:3001/speak \
     -H "Authorization: Bearer your-generated-secret" \
     -H "Content-Type: application/json" \
     -d '{"text": "Hello world"}'
   

​

Security notes

• Use at least 32 random bytes; rotate periodically and never commit secrets to VCS.
• Always terminate TLS before traffic reaches Sayna so the bearer token stays encrypted in transit.
• Pair with IP allowlists when you use this mode for back-office tools.

​

Option B — Delegated JWT authentication

​

1. Generate signing keys

# RSA
oopenssl genrsa -out auth_private_key.pem 2048
oopenssl rsa -in auth_private_key.pem -pubout -out auth_public_key.pem
chmod 600 auth_private_key.pem
chmod 644 auth_public_key.pem

# or ECDSA
oopenssl ecparam -genkey -name prime256v1 -noout -out auth_private_key.pem
oopenssl ec -in auth_private_key.pem -pubout -out auth_public_key.pem

​

2. Configure Sayna

AUTH_REQUIRED=true
AUTH_SERVICE_URL=https://your-auth-service.com/auth
AUTH_SIGNING_KEY_PATH=/path/to/auth_private_key.pem
AUTH_TIMEOUT_SECONDS=5

​

3. Implement the auth service

1. Accept POST requests whose body is the JWT Sayna generated.
2. Verify the JWT signature using the public key (RS256 or ES256).
3. Validate the extracted bearer token and any contextual data.
4. Return 200 OK (allow) or 401 Unauthorized (deny). Other 4xx map to 401, 5xx become 502, and timeouts surface as 503 upstream.

const express = require('express');
const jwt = require('jsonwebtoken');
const fs = require('fs');

const app = express();
const publicKey = fs.readFileSync('auth_public_key.pem');

app.post('/auth', express.text(), (req, res) => {
  try {
    const payload = jwt.verify(req.body, publicKey, { algorithms: ['RS256', 'ES256'] });
    const isValid = validateToken(payload.token);
    if (isValid) {
      res.status(200).send('OK');
    } else {
      res.status(401).send('Invalid token');
    }
  } catch (error) {
    res.status(401).send('JWT verification failed');
  }
});

app.listen(3000);

​

Environment variables

​

JWT payload schema (delegated mode)

{
  "sub": "sayna-auth",
  "iat": 1234567890,
  "exp": 1234568190,
  "auth_data": {
    "token": "bearer-token-from-auth-header",
    "request_body": {"text": "request body as JSON"},
    "request_headers": {
      "content-type": "application/json",
      "user-agent": "client-agent"
    },
    "request_path": "/speak",
    "request_method": "POST"
  }
}

• sub: Always sayna-auth so your service knows who issued the JWT.
• iat / exp: Issued-at plus 5-minute expiration.
• auth_data.token: Bearer token extracted from the Authorization header.
• auth_data.request_body: JSON payload of the HTTP request.
• auth_data.request_headers: Filtered headers (excludes authorization, cookie, x-forwarded-*, x-sayna-*, host, x-real-ip).
• auth_data.request_path / request_method: Full request context for policy decisions.

​

Verification checklist

def verify_auth_request(jwt_string, public_key):
    payload = jwt.decode(jwt_string, public_key, algorithms=['RS256', 'ES256'])
    if payload['sub'] != 'sayna-auth':
        return 401, 'Invalid JWT subject'
    now = int(time.time())
    if abs(now - payload['iat']) > 60:
        return 401, 'JWT too old'
    auth_data = payload['auth_data']
    bearer_token = auth_data['token']
    if not is_valid_token(bearer_token):
        return 401, 'Invalid bearer token'
    return 200, 'OK'

​

Protected endpoints

• POST /speak
• GET /voices
• POST /livekit/token
• Any future REST routes you add to the protected router

• GET / (health)
• GET /ws (WebSocket handshake — see the WebSocket Auth roadmap below)

​

WebSocket authentication status

1. Authenticate during the HTTP upgrade by reading query parameters or headers.
2. Require an auth payload inside the first config message.
3. Or leave /ws public but scope LiveKit mirroring to trusted rooms.

​

Usage examples

# API secret
curl -X GET http://localhost:3001/voices \
  -H "Authorization: Bearer $AUTH_API_SECRET"

# JWT-based
curl -X POST http://localhost:3001/speak \
  -H "Authorization: Bearer user-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"text": "Different user"}'

​

Error responses

{
  "error": "error_code",
  "message": "Human-readable error message"
}

​

Mapping auth service responses

​

Security considerations

• Private keys: Store private keys with chmod 600, never commit them, and rotate periodically.
• Network security: Run Sayna + auth service over HTTPS/TLS. Consider mutual TLS between the two if you run them across trust zones.
• Token validation: Reject replayed JWTs by checking iat; combine with short expirations.
• Error handling: Return generic error bodies to clients but log detailed errors internally for auditing.
• Replay protection: Compare iat against now (±60 seconds) before trusting the payload.