Auth Modes

Every gateway API has an auth_mode that controls how end users prove their identity. Pick the model that fits your product.

Comparison

Aerostack Auth (default)

Aerostack manages user accounts. Users sign in with email + OTP code — no passwords. The chat widget handles the full flow automatically.

How it works:

1. Widget checks localStorage for a JWT
2. If none, shows OTP sign-in (email → 6-digit code)
3. On verify → JWT stored in localStorage
4. JWT sent as Authorization: Bearer <jwt> on all gateway requests
5. On 401 → silent refresh attempted, then re-login

Set it in the dashboard: AI Products → your API → Settings → Auth Mode → Aerostack

Use with the SDK:

// React — useAuth provides the JWT, pass it to useGatewayChat
const { tokens } = useAuth()
 
const { messages, sendMessage } = useGatewayChat({
  apiSlug: 'my-chatbot',
  token: tokens?.accessToken,  // user JWT from Aerostack auth
})

Use with the chat widget — handled automatically, no config needed:

<script src="https://hub.aerostack.io/chat.js"
  data-project="my-project"
  data-api="my-chatbot">
</script>

Consumer Key Only

No user accounts in Aerostack. Your backend issues consumer keys (ask_live_) and passes them to the client. You manage session identity — Aerostack just verifies the key and tracks quota per key.

How it works:

1. You create a consumer key in the dashboard (or via API)
2. Your backend securely delivers the key to the client (e.g. in a signed session)
3. Client includes Authorization: Bearer ask_live_xxx on gateway requests
4. Aerostack validates key → enforces quota → no user lookup needed

Set it in the dashboard: AI Products → your API → Settings → Auth Mode → Consumer Key Only

Use with the SDK:

// Universal SDK
const ai = new AerostackClient({ baseUrl: 'https://api.aerocall.ai/v1' })
ai.gateway.setConsumerKey(await fetchKeyFromYourBackend())
 
await ai.gateway.stream({
  apiSlug: 'my-chatbot',
  messages: [{ role: 'user', content: input }],
  onToken: delta => appendToUI(delta),
})

// React hook
const { messages, sendMessage } = useGatewayChat({
  apiSlug: 'my-chatbot',
  consumerKey: consumerKeyFromYourBackend,
})

BYO JWT (Bring Your Own Auth)

You issue JWTs with your own auth system. Aerostack validates them against your JWKS endpoint and extracts a user ID for quota tracking. No user data is stored in Aerostack.

How it works:

1. You configure a JWKS URL (e.g. https://myapp.com/.well-known/jwks.json) and user ID claim (e.g. sub)
2. Aerostack caches your public keys (1h TTL in KV)
3. User sends your JWT as Authorization: Bearer <your-jwt>
4. Aerostack validates signature → extracts sub (or your claim) → uses as consumer ID for quota tracking
5. No user record created in Aerostack

Set it in the dashboard: AI Products → your API → Settings → Auth Mode → My Own Auth (BYO JWT)

Enter:

• JWKS endpoint: https://myapp.com/.well-known/jwks.json
• User ID claim: sub (or user_id, uid, etc.)

Or via API:

curl -X PUT https://api.aerocall.ai/api/v1/gateway/apis/:apiId/auth-mode \
  -H "Authorization: Bearer <your-developer-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_mode": "byo-jwt",
    "byo_jwt_config": {
      "jwks_url": "https://myapp.com/.well-known/jwks.json",
      "user_id_claim": "sub"
    }
  }'

Use with the SDK — pass your JWT directly:

// React — your JWT from your own auth context
const { user } = useYourOwnAuth()  // your existing auth hook
 
const { messages, sendMessage } = useGatewayChat({
  apiSlug: 'my-chatbot',
  token: user.jwt,  // your JWT — Aerostack validates it against your JWKS
})

// Universal SDK
await ai.gateway.stream({
  apiSlug: 'my-chatbot',
  messages: [{ role: 'user', content: input }],
  onToken: delta => appendToUI(delta),
})
// Set your JWT as the consumer key
ai.gateway.setConsumerKey(yourJwt)

Switching modes

You can change auth mode at any time from the dashboard. Existing consumer keys remain valid in all modes — only the JWT validation path changes.