veylant/deploy/onboarding/README.md

Veylant IA — Pilot Client Onboarding

Operational in under one working day.

Prerequisites

Tool	Version	Notes
curl	any	Standard on macOS/Linux
python3	3.8+	JSON parsing in scripts
Veylant IA proxy	running	make dev or production URL
Admin JWT	valid	Issued by Keycloak for the platform admin

Scripts

onboard-tenant.sh — Full tenant provisioning

Provisions a new client tenant end-to-end:

1. Checks proxy health
2. Creates the tenant admin user
3. Seeds 4 routing policy templates (HR, Finance, Engineering, Catchall)
4. Configures rate limits
5. Prints a verification summary

# Make executable (once)
chmod +x onboard-tenant.sh import-users.sh

# Set required variables
export VEYLANT_URL=https://api.veylant.ai
export VEYLANT_ADMIN_TOKEN=<platform-admin-jwt>
export TENANT_ADMIN_EMAIL=admin@client.example

# Optional overrides
export TENANT_ADMIN_FIRST=Marie
export TENANT_ADMIN_LAST=Dupont
export RPM=2000
export BURST=400

./onboard-tenant.sh

import-users.sh — Bulk user import from CSV

Imports a list of users from a CSV file. Idempotent — already-existing users (HTTP 409) are skipped without error.

export VEYLANT_URL=https://api.veylant.ai
export VEYLANT_ADMIN_TOKEN=<admin-jwt>

./import-users.sh sample-users.csv

sample-users.csv — Example CSV format

email,first_name,last_name,department,role
alice.martin@corp.example,Alice,Martin,HR,user
bob.dupont@corp.example,Bob,Dupont,Finance,user

Roles: admin, manager, user, auditor

Day-1 Checklist

• Run onboard-tenant.sh to provision the tenant
• Customize the CSV with real user data
• Run import-users.sh to bulk-import users
• Issue Keycloak JWTs for each user (via your IdP admin console)
• Share the integration guide with developers
• Verify a test request: curl -X POST $VEYLANT_URL/v1/chat/completions ...
• Confirm audit logs appear: GET /v1/admin/logs

Rate Limit Defaults

Setting	Default	Override via
Requests/min	1 000	RPM env var
Burst	200	BURST env var
Per-user RPM	200	RPM ÷ 5
Per-user burst	40	BURST ÷ 5

Limits can be adjusted at any time without restart via:

curl -X PUT $VEYLANT_URL/v1/admin/rate-limits/<tenant_id> \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"requests_per_min": 3000, "burst_size": 600, "is_enabled": true}'

Troubleshooting

Symptom	Check
VEYLANT_URL not set	Export the variable and retry
HTTP 401 on API calls	JWT may have expired — refresh via Keycloak
HTTP 403	Token role is not admin — use the platform admin token
User creation fails (HTTP 500)	Check PostgreSQL is running: make health
PII not working	Ensure PII sidecar is up: curl http://localhost:8091/healthz