5-minute guide

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. 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 the owner of a new organization on the free plan.

  2. 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. 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, and allowedModels, then submit.

    The secret is shown exactly once. Copy it immediately to a secure location. It starts with air_sk_ and is hashed with SHA-256 before being stored. If you lose it, revoke the key and create a new one.

    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 in key.secret. Save it.

  4. 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": true for Server-Sent Events streaming. AIRouter passes through the upstream stream and translates each chunk to OpenAI'schat.completion.chunk shape on the fly.

  5. 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 theusage_records collection 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