From signup to your first request
This guide walks you through creating an AIRouter account, adding a provider credential, generating your first tenant API key, sending a chat completion request, and viewing usage in the dashboard. Total time: about five minutes.
Prerequisites
- An email address and a password for signup.
- An
air_sk_...capable HTTP client (curl, Postman, the OpenAI SDK, the Anthropic SDK, or the Google AI SDK all work). - For free testing: an OpenRouter account (free) and an OpenRouter API key. You can sign up at openrouter.ai/keys.
Walkthrough
- 1
Create your AIRouter account
Open /auth/signup and enter your email and password. AIRouter authentication is backed by Lightbase; the signup endpoint bootstraps your user, organization, membership, free subscription, and system settings in a single transaction.
curl -X POST https://airouter-beta.pages.dev/api/auth/signup \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com","password":"your-password","name":"Your Name"}'The response sets two HTTP-only cookies (
air_access,air_refresh) and returns your user id and organization id. You are now theownerof a new organization on the free plan. - 2
Add a provider credential
Open /app/providers and click Add credential. Pick OpenRouter from the catalog to access free models. Paste your OpenRouter API key (starts with
sk-or-v1-...) and save.The credential is encrypted at rest via Lightbase field-level encryption and is never returned to the browser. Only a masked last-4 view is shown in the dashboard.
Alternatively, add a credential programmatically via the admin API. You must be logged into the dashboard (the session cookies are sent automatically):
curl -X POST https://airouter-beta.pages.dev/api/admin/credentials \ -H "Content-Type: application/json" \ -b "air_access=...; air_refresh=..." \ -d '{ "providerId": "openrouter", "label": "OpenRouter free", "credential": "sk-or-v1-...", "priority": 100, "weight": 1 }' - 3
Create a tenant API key
Open /app/api-keys and click Create key. Pick a label, optionally restrict by scope (e.g.
chat),allowedProviders, andallowedModels, then submit.Programmatic equivalent:
curl -X POST https://airouter-beta.pages.dev/api/admin/keys \ -H "Content-Type: application/json" \ -b "air_access=...; air_refresh=..." \ -d '{ "label": "production", "scopes": ["chat", "embeddings"], "allowedProviders": ["openrouter"], "allowedModels": ["openai/gpt-4o-mini"], "rateLimitPerMin": 60, "rateLimitPerDay": 10000 }'The response returns the plaintext
air_sk_...secret inkey.secret. Save it. - 4
Send your first request
With your
air_sk_...key in hand, call the OpenAI-compatible chat completions endpoint. AIRouter will authenticate, resolve the routing rule (defaultpriority-failover), pick your OpenRouter credential, translate the request upstream, fetch the response, translate it back to OpenAI shape, and return it.curl -X POST https://airouter-beta.pages.dev/api/v1/chat/completions \ -H "Authorization: Bearer air_sk_..." \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-4o-mini", "messages": [ {"role": "user", "content": "Hello, AIRouter!"} ] }'Expected response (abbreviated):
{ "id": "chatcmpl-...", "object": "chat.completion", "created": 1730000000, "model": "openai/gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help you today?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 9, "completion_tokens": 9, "total_tokens": 18 } }Add
"stream": truefor Server-Sent Events streaming. AIRouter passes through the upstream stream and translates each chunk to OpenAI'schat.completion.chunkshape on the fly. - 5
View your usage
Open /app/usage to see today's request count, token usage, estimated cost, and the daily chart broken down by provider and endpoint. Switch the range between 7, 30, and 90 days.
Every successful request is recorded fire-and-forget into the
usage_recordscollection in Lightbase. Each record contains the organization id, API key id, provider id, credential id, endpoint path, model, input/output tokens, cache read/write tokens, estimated cost in USD, latency, status code, client IP, user agent, and the routing rule id that produced it.
Next steps
- Read the API Reference for the full endpoint surface.
- Browse the provider catalog and add more credentials.
- Configure routing strategies for cost, latency, or failover.
- Build a combo for multi-step orchestration.
- Review the security model before going to production.