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

# Authentication

> Authenticate requests to the BindAI REST API using API keys.

# Authentication

The BindAI REST API v0.1 uses a simple environment-based API-key authentication mechanism for protected endpoints.

The authentication model is:

```text theme={null}
Client
   |
   | Authorization: Bearer <API key>
   v
BindAI API
   |
   v
Protected Resource
```

The API key is configured through the `BINDAI_API_KEY` environment variable.

Authentication is intentionally lightweight for the initial v0.1 public API. There is no database-backed identity system, user-management system, or built-in multi-tenant authorization layer.

***

# API Key Configuration

Set the API key in the environment where the BindAI API process is running:

```text theme={null}
BINDAI_API_KEY=your-secret-key
```

The current authentication implementation reads this value directly from the process environment.

For local development, the value can be supplied through the shell environment or through the environment-file mechanism used by the deployment.

Do not commit real API keys to source control.

***

# Authorization Header

Clients authenticate using the HTTP `Authorization` header with the Bearer scheme:

```http theme={null}
Authorization: Bearer your-secret-key
```

For example:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/projects
```

The value after `Bearer` must match the configured `BINDAI_API_KEY`.

The current implementation compares the complete authorization value against:

```text theme={null}
Bearer <BINDAI_API_KEY>
```

The comparison is therefore based on the configured single API key.

***

# Protected Endpoints

The v0.1 API protects the following resource groups with API-key authentication:

```text theme={null}
/api/v1/agents
/api/v1/workflows
/api/v1/projects
/api/v1/runs
```

Examples include:

```text theme={null}
GET  /api/v1/agents
POST /api/v1/agents/{agent_name}/run
POST /api/v1/agents/{agent_name}/stream

GET  /api/v1/workflows
POST /api/v1/workflows/{workflow_id}/run

GET  /api/v1/projects
GET  /api/v1/projects/{project_name}

POST /api/v1/runs
GET  /api/v1/runs/{run_id}
```

These endpoints require a valid Bearer token.

Authentication is applied at the router level, so the protected resource groups consistently use the same authentication dependency.

***

# Public Health Endpoint

The health endpoint does not require authentication:

```http theme={null}
GET /health
```

For example:

```bash theme={null}
curl http://localhost:8000/health
```

Example response:

```json theme={null}
{
  "status": "ok",
  "service": "bindai-api"
}
```

Keeping `/health` public allows deployment infrastructure and container health checks to verify basic API availability without storing API credentials.

The health endpoint reports API application availability. It does not perform a complete health check of every configured model provider, connection, or external dependency.

***

# Authentication Flow

For a normally configured deployment, the request flow is:

```text theme={null}
Client
  |
  | HTTP Request
  | Authorization: Bearer <API key>
  v
BindAI API
  |
  +---- Missing header ------> 401
  |
  +---- Invalid key ---------> 401
  |
  +---- Valid key
             |
             v
       Protected Resource
```

If the `Authorization` header is missing, or its value does not exactly match the configured Bearer token, the authentication dependency raises `401 Unauthorized`.

***

# Missing Authentication

A protected endpoint called without an authorization header is rejected when API-key authentication is configured.

For example:

```bash theme={null}
curl http://localhost:8000/api/v1/projects
```

The request does not contain the required Bearer token.

The API returns:

```text theme={null}
401 Unauthorized
```

The response identifies the authentication failure rather than executing the protected resource.

***

# Invalid Authentication

A request with an incorrect API key is also rejected.

For example:

```bash theme={null}
curl \
  -H "Authorization: Bearer wrong-key" \
  http://localhost:8000/api/v1/projects
```

The API returns:

```text theme={null}
401 Unauthorized
```

The authentication dependency reports:

```text theme={null}
Invalid or missing API key.
```

***

# Correct Authentication

A request containing the configured API key is allowed to reach the protected resource.

For example:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/projects
```

If authentication succeeds, the requested resource is processed normally.

Authentication only establishes access to the protected API route. The requested resource must still exist and be correctly configured.

For example, a valid API key does not guarantee that a requested agent or workflow exists.

***

# Missing API Key Configuration

The API expects `BINDAI_API_KEY` to be configured before protected routes are served.

If the environment variable is not configured, the current authentication dependency raises a configuration `RuntimeError` rather than returning a normal `401 Unauthorized` response.

Conceptually:

```text theme={null}
BINDAI_API_KEY configured
        |
        v
Normal API-key validation
        |
        +---- Missing/invalid request key ---> 401
        |
        +---- Valid request key ------------> Protected resource
```

If `BINDAI_API_KEY` itself is missing:

```text theme={null}
BINDAI_API_KEY missing
        |
        v
Authentication dependency
        |
        v
Runtime configuration error
```

Therefore, deployments should configure `BINDAI_API_KEY` before exposing protected API routes.

For example:

```text theme={null}
BINDAI_API_KEY=your-secret-key
```

This behavior is an implementation detail of the current v0.1 authentication layer and may become more explicit or configurable in a future release.

***

# PowerShell

When using Windows PowerShell, the API key can be stored in an environment variable:

```powershell theme={null}
$env:BINDAI_API_KEY = "your-secret-key"
```

A request can then be made with:

```powershell theme={null}
Invoke-RestMethod `
  -Uri http://localhost:8000/api/v1/projects `
  -Headers @{ Authorization = "Bearer $env:BINDAI_API_KEY" }
```

This keeps the key out of the request command itself.

***

# Docker

When running the API with Docker, provide the key through the container environment:

```bash theme={null}
docker run --rm -p 8000:8000 \
  -e BINDAI_API_KEY=your-secret-key \
  bindai-api
```

The API reads the key from the container environment.

Other application credentials can be supplied through environment variables as required by the configured BindAI application.

Do not place production credentials directly into a Dockerfile.

***

# Docker Compose

When using Docker Compose, the API key can be supplied through the environment configuration.

For example:

```text theme={null}
BINDAI_API_KEY=your-secret-key
```

The repository's Compose configuration passes the value into the API container.

Do not commit production secrets into `docker-compose.yml`.

For production deployments, use the secret-management facilities provided by the hosting environment when available.

***

# Environment Configuration

A local BindAI deployment may contain several different credentials:

```text theme={null}
BINDAI_API_KEY=your-secret-key

OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GEMINI_API_KEY=your-google-key
GROQ_API_KEY=your-groq-key
OPENROUTER_API_KEY=your-openrouter-key
PINECONE_API_KEY=your-pinecone-key
```

Only configure credentials required by the application.

The exact provider and integration credentials depend on the models, memory, knowledge systems, and connections used by the project.

The BindAI API key has a different purpose from these credentials: it authenticates API clients to the BindAI API.

***

# Secret Management

API keys should be treated as secrets.

Do not store production API keys in:

* Source code
* Git repositories
* Dockerfiles
* Public documentation
* Public configuration files
* Client-side JavaScript
* URLs
* Query parameters
* Error messages
* Ordinary application logs

Use environment variables or a dedicated secret-management system.

***

# Key Generation

The BindAI v0.1 API does not provide a built-in API-key generation service.

The configured key is supplied by the deployment environment.

A deployment can generate a strong random secret using an appropriate operating-system or secret-management facility.

For example, Python can generate a random token:

```bash theme={null}
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

The generated value can then be configured as:

```text theme={null}
BINDAI_API_KEY=<generated-value>
```

The generated key should be kept private.

***

# Key Rotation

The v0.1 authentication model uses one configured API key.

Changing the value of `BINDAI_API_KEY` changes the key accepted by the API after the application environment is refreshed and the API process is restarted or redeployed.

A simple rotation process is:

```text theme={null}
Generate New Key
       |
       v
Update Deployment Secret
       |
       v
Restart / Redeploy API
       |
       v
Update Clients
       |
       v
Verify Access
```

Because v0.1 does not provide persistent key management, applications that require multiple simultaneously valid keys need an authentication layer outside the basic BindAI API authentication mechanism.

***

# Client Security

Clients should protect their BindAI API keys in the same way they protect other service credentials.

Avoid putting a BindAI API key into:

* Browser source code
* Public mobile applications
* Public GitHub repositories
* Frontend configuration shipped to users
* URLs
* Query parameters

Prefer a trusted backend service when exposing BindAI functionality to untrusted clients.

For example:

```text theme={null}
User
 |
 v
Your Application
 |
 | Server-side API key
 v
BindAI API
```

rather than:

```text theme={null}
User Browser
 |
 | BindAI API key
 v
BindAI API
```

The second design exposes the credential to the client.

***

# HTTPS

API-key authentication should be used over HTTPS when the API is exposed outside a trusted local network.

A production deployment should normally look like:

```text theme={null}
Client
   |
   | HTTPS
   v
TLS / Reverse Proxy
   |
   | HTTP or HTTPS
   v
BindAI API
```

Do not transmit API keys over unencrypted public HTTP connections.

For local development, `http://localhost:8000` is appropriate for testing.

***

# Reverse Proxy Deployment

A production deployment may place a reverse proxy in front of the BindAI API:

```text theme={null}
Internet
   |
   v
Reverse Proxy
   |
   v
BindAI API
```

The reverse proxy can provide infrastructure-level controls such as:

* TLS termination
* Network restrictions
* Rate limiting
* Request-size limits
* Access logging
* IP filtering

The BindAI API remains responsible for its application-level API-key validation.

***

# Rate Limiting

The v0.1 BindAI API authentication layer does not provide built-in rate limiting.

When exposing the API publicly, rate limiting should be provided by the surrounding infrastructure when required.

For example:

```text theme={null}
Client
   |
   v
Rate Limiter
   |
   v
BindAI API
```

Rate limits can help protect against:

* Accidental request loops
* Excessive API usage
* Denial-of-service attempts
* Unexpected client behavior

The appropriate limits depend on the workload and deployment environment.

***

# Authentication and Agent Access

Authentication protects access to the REST API.

It does not determine what an individual agent is allowed to do.

For example:

```text theme={null}
API Key
   |
   v
BindAI API
   |
   v
Agent
   |
   +---- Tool A
   |
   +---- Tool B
   |
   +---- Connection
```

Tool and connection permissions are separate concerns.

An API client possessing a valid API key can reach the protected API resources exposed by the current v0.1 API.

Fine-grained per-user, per-agent, or per-tool authorization is outside the current authentication implementation.

***

# Authentication and Connections

Connections may require their own credentials.

For example:

```text theme={null}
BindAI API
   |
   +---- Agent
   |
   +---- Connection
              |
              +---- Slack credential
              +---- Google OAuth token
              +---- GitHub token
```

The BindAI API key and external-service credentials serve different purposes.

The API key authenticates the client to BindAI.

The connection credential authenticates BindAI to the external service.

Do not expose external-service credentials to API clients unnecessarily.

***

# Authentication and Model Providers

Model-provider credentials are also separate from the BindAI API key.

For example:

```text theme={null}
API Client
    |
    | BindAI API key
    v
BindAI API
    |
    | Provider credential
    v
Model Provider
```

The API client does not normally need direct access to the provider credential.

This allows the BindAI deployment to control which model providers are available to the application.

***

# Authentication and Background Runs

Background-run endpoints require the same API authentication as other protected resources.

For example:

```http theme={null}
POST /api/v1/runs
```

requires:

```http theme={null}
Authorization: Bearer your-secret-key
```

The returned run ID can then be used to query the run:

```http theme={null}
GET /api/v1/runs/{run_id}
```

The run ID is not a replacement for API authentication.

Clients must continue to provide valid authentication when querying protected run resources.

***

# Authentication Errors

Authentication failures should be treated differently from application execution failures.

Authentication failure:

```text theme={null}
Client
  |
  v
Invalid API Key
  |
  v
401 Unauthorized
```

Application failure:

```text theme={null}
Client
  |
  v
Valid API Key
  |
  v
Application
  |
  v
Execution Failure
```

A valid API key only grants access to the API endpoint. It does not guarantee that the requested agent, workflow, provider, connection, or background run will succeed.

***

# Operational Logging

Authentication-related operational information can be useful for debugging and security monitoring.

However, never log the API key itself.

Safe information may include:

* Request timestamp
* Endpoint
* HTTP method
* Response status
* Request duration
* Application-level request identifier

Avoid logging:

```text theme={null}
Authorization: Bearer your-secret-key
```

or any equivalent secret value.

***

# Development vs Production

Local development can use a simple environment variable:

```text theme={null}
BINDAI_API_KEY=local-development-key
```

Production deployments should use a strong randomly generated value stored in a secure secret-management system.

Conceptually:

```text theme={null}
Development
    |
    v
Environment Variable


Production
    |
    v
Secret Manager
    |
    v
Deployment Environment
    |
    v
BINDAI_API_KEY
```

Do not reuse production credentials in development environments.

***

# Current v0.1 Authentication Model

The current authentication architecture is intentionally small:

```text theme={null}
Environment
    |
    | BINDAI_API_KEY
    v
BindAI API
    |
    | Authorization: Bearer <key>
    v
Authenticated Request
```

The API validates the supplied Bearer token against the configured environment value.

The current implementation does not provide:

* Database-backed identity
* User accounts
* Role management
* Multiple managed API keys
* OAuth
* OpenID Connect
* Built-in multi-tenant authorization
* Persistent API-key storage
* API-key expiration or revocation

These are outside the current v0.1 authentication implementation.

***

# Future Authentication

Future BindAI releases may introduce more advanced authentication and authorization capabilities.

Potential areas include:

* Multiple API keys
* Persistent API-key management
* Key expiration
* Key revocation
* User accounts
* OAuth
* OpenID Connect
* Role-based access control
* Per-project permissions
* Per-agent permissions
* Per-tool permissions
* Multi-tenant authorization
* Audit logging

These capabilities are not part of the BindAI v0.1 authentication implementation.

Applications requiring them today can place an identity and authorization layer in front of the BindAI API.

***

# Security Checklist

Before exposing a BindAI API deployment publicly:

* Generate a strong API key.
* Store the key securely.
* Configure `BINDAI_API_KEY`.
* Do not commit the key to source control.
* Use HTTPS.
* Do not put the API key in URLs.
* Do not expose the key in browser code.
* Do not log the key.
* Use least-privilege credentials for external connections.
* Protect provider credentials.
* Consider rate limiting.
* Monitor authentication failures.
* Rotate credentials when appropriate.
* Restrict network access where possible.

***

# Testing Authentication

The API package includes authentication tests.

Run the API test suite with:

```bash theme={null}
uv run pytest packages/bindai-api/tests -q
```

Authentication behavior should be tested for at least:

* Valid API key
* Invalid API key
* Missing API key
* Public health endpoint

A basic manual test can also verify the behavior.

Without authentication:

```bash theme={null}
curl http://localhost:8000/api/v1/projects
```

With authentication:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/projects
```

When `BINDAI_API_KEY` is configured, the first request should be rejected with `401 Unauthorized`.

The second request should be processed when the key matches `BINDAI_API_KEY`.

***

# API Authentication Summary

BindAI v0.1 uses a simple environment-based Bearer API key.

Configuration:

```text theme={null}
BINDAI_API_KEY=your-secret-key
```

Client header:

```http theme={null}
Authorization: Bearer your-secret-key
```

Public endpoint:

```http theme={null}
GET /health
```

Protected endpoints include:

```text theme={null}
/api/v1/agents
/api/v1/workflows
/api/v1/projects
/api/v1/runs
```

For a normally configured API:

```text theme={null}
Missing/invalid Bearer key  -> 401 Unauthorized
Valid Bearer key            -> protected resource
Missing BINDAI_API_KEY      -> server configuration error
```

The current implementation is intentionally lightweight and suitable for the initial public API.

For production deployments, combine BindAI API-key authentication with appropriate HTTPS, secret management, network controls, monitoring, and rate limiting.

More advanced identity and authorization capabilities are planned for future BindAI releases.