> ## Documentation Index
> Fetch the complete documentation index at: https://agumbe.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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**

```typescript theme={null}
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**

```python theme={null}
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:

```json theme={null}
{
  "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