Authentication

Authentication in Agumbe AI Gateway is designed to support both interactive product workflows and production-grade application traffic.

At a high level, the gateway accepts authenticated requests in two ways:

1. Gateway API keys for backend, service-to-service, and production integrations
2. Session-based authentication for signed-in users working through the Agumbe Console

For most customers integrating Agumbe into a real application, the recommended approach is to use a Gateway API key from your backend service.

Why authentication matters

Every authenticated request helps the gateway determine:

• which tenant owns the traffic
• which user or system is making the call
• which app policy should apply
• which limits and guardrails should be enforced
• how request logs, usage, and billing metadata should be attributed

In other words, authentication is not only about access control. It is also how Agumbe connects a request to the right operational and policy context.

Authentication methods

Gateway API keys

Gateway API keys are the primary authentication method for application traffic.

Use a Gateway API key when:

• your backend sends chat or embeddings requests to Agumbe
• a worker or internal service calls the gateway
• you want a stable credential for production use
• you need app-level or tenant-level policy enforcement

Send the key as a bearer token:

Authorization: Bearer AGUMBE_API_KEY

Example:

curl https://api.agumbe.ai/api/v1/llm/chat/completions \
  -H "Authorization: Bearer $AGUMBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "smart-default",
    "messages": [
      {
        "role": "user",
        "content": "Summarize this support message."
      }
    ]
  }'

Gateway API keys are best suited for server-side use only. They should never be embedded in frontend code, mobile applications, browser extensions, or any environment where end users can inspect or extract credentials.

Session authentication

Session authentication is used when a signed-in user interacts with Agumbe through the Console.

This flow is useful for:

• trying requests in the playground
• configuring guardrails
• viewing request logs
• managing platform settings from the Console

With session authentication, the gateway reads the signed-in user’s session context and associates requests with that user and tenant.

This is convenient for interactive product workflows, but it is not the recommended authentication model for production application traffic.

Recommended production pattern

For almost every customer integration, use this pattern:

Your client application -> Your backend -> Agumbe AI Gateway

This gives you several advantages:

• your Gateway API key stays private
• your backend can decide which app or policy to use
• you can add retries, logging, request validation, and business rules in one place
• you keep full control over how end-user actions map to gateway traffic

API key scopes

Agumbe supports two important API key usage patterns:

• tenant-scoped API keys
• app-scoped API keys

Choosing the right scope is one of the most important authentication decisions you will make.

Tenant-scoped API keys

A tenant-scoped API key can be used across multiple apps within the same tenant.

Use a tenant-scoped key when:

• one backend service powers multiple AI workflows
• you want to choose the app policy per request
• your platform has several app contexts behind one service

When you use a tenant-scoped key, you should send the app identifier in the request using:

agumbe_guardrails_app_id

Example:

{
  "model": "smart-default",
  "messages": [
    {
      "role": "user",
      "content": "Draft a safe reply to this customer."
    }
  ],
  "agumbe_guardrails_app_id": "app_support"
}

This tells the gateway which app’s guardrail policy should apply to the request.

App-scoped API keys

An app-scoped API key is bound to one app.

Use an app-scoped key when:

• a workload should always use one app policy
• you want stronger isolation between environments or workloads
• you want to reduce the risk of sending traffic under the wrong app context
• a service or deployment has a single clear AI purpose

With an app-scoped key, the gateway automatically applies the bound app’s policy. You do not need to pass agumbe_guardrails_app_id in each request.

Example:

{
  "model": "smart-default",
  "messages": [
    {
      "role": "user",
      "content": "Summarize this document."
    }
  ]
}

If an app-scoped key is used with a different agumbe_guardrails_app_id, the gateway rejects the request.

This helps prevent policy leakage across apps.

How the gateway resolves identity

When a request is authenticated successfully, the gateway associates it with runtime context such as:

• tenant
• user or system identity
• app
• key scope
• subject type

This context is then used across the platform for:

• guardrail policy lookup
• usage controls
• request logging
• observability
• spend attribution
• rate limiting and quota enforcement

That means the credential you choose affects more than access. It shapes how the platform interprets and governs traffic.

Example: authenticating with a backend SDK

If you are integrating from a backend service, configure your SDK with your Gateway API key and the Agumbe base URL.

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AGUMBE_API_KEY,
  baseURL: "https://api.agumbe.ai/api/v1/llm",
});

async function run() {
  const response = await client.chat.completions.create({
    model: "smart-default",
    messages: [
      {
        role: "user",
        content: "Explain authentication in one paragraph."
      }
    ]
  });

  return response.choices[0]?.message?.content;
}

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGUMBE_API_KEY"],
    base_url="https://api.agumbe.ai/api/v1/llm",
)

response = client.chat.completions.create(
    model="smart-default",
    messages=[
        {
            "role": "user",
            "content": "Explain authentication in one paragraph."
        }
    ]
)

print(response.choices[0].message.content)

Handling app selection correctly

If your backend uses a tenant-scoped key, your service should decide which app policy applies before it sends the request to Agumbe.

This usually happens in one of these ways:

• each route maps to a fixed app ID
• each customer workflow maps to a fixed app ID
• your backend derives the correct app ID from the request context
• you separate staging, development, and production by app ID

This pattern gives you flexibility, but it also means your backend is responsible for choosing the right app context.

If that logic should never vary, prefer an app-scoped key instead.

Security best practices

Use the following authentication practices in production.

Keep keys server-side

Always store Gateway API keys in backend environment variables or a secure secrets manager.

Do not expose them to browsers, mobile clients, or public frontend bundles.

Separate environments

Use different keys for development, staging, and production.

This makes it easier to:

• rotate credentials safely
• isolate request logs by environment
• apply different guardrails
• reduce blast radius if a key must be revoked

Prefer app-scoped keys for sensitive workloads

If a workflow handles regulated content, internal knowledge, customer support, finance, or high-sensitivity operations, use an app-scoped key whenever possible.

This reduces the chance of applying the wrong policy set.

Rotate keys deliberately

Treat Gateway API keys as production credentials. Rotate them through your standard secret management process and revoke unused keys promptly.

Keep authentication logic simple

The safest production systems are usually the simplest ones. Avoid building overly dynamic app selection logic unless your architecture truly needs it.

Common authentication errors

When authentication fails, the gateway returns a structured error response.

Example:

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "param": null,
    "code": "unauthorized"
  }
}

Common authentication-related errors include:

• unauthorized when no valid bearer token or session is present
• app_mismatch when an app-scoped key is used with the wrong app ID
• forbidden when an operation requires elevated permissions
• guardrail_policy_forbidden when an app credential attempts to update guardrail policies

When to use which method

Choose Gateway API keys if:

• you are integrating Agumbe into an application
• you need production-ready authentication
• your backend or worker is calling the gateway
• you want stable credential management and policy control

Choose session authentication if:

• you are working inside the Agumbe Console
• you are testing in the playground
• you are configuring product settings interactively

Choose a tenant-scoped key if:

• one service needs to work across multiple apps
• your backend selects the app policy per request

Choose an app-scoped key if:

• the workload should always use one app policy
• you want tighter isolation and safer production defaults

Recommended starting point

If you are integrating Agumbe for the first time, start with:

• a backend service
• one Gateway API key
• one app-scoped key for one real workload
• one stable model alias such as smart-default
• one app-level guardrail policy

This gives you the cleanest path to production and the least ambiguity in how requests are authenticated and governed.

Next steps

Once authentication is set up, the next pages to read are:

• Models and Aliases to understand how model selection works
• Guardrails to learn how app-level policies are applied
• Go to Production for deployment and operational guidance