Authentication

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

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:

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:

Authorization: Bearer your-secret-key

For example:

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:

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:

/api/v1/agents
/api/v1/workflows
/api/v1/projects
/api/v1/runs

Examples include:

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:

GET /health

For example:

curl http://localhost:8000/health

Example response:

{
  "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:

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:

curl http://localhost:8000/api/v1/projects

The request does not contain the required Bearer token. The API returns:

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:

curl \
  -H "Authorization: Bearer wrong-key" \
  http://localhost:8000/api/v1/projects

The API returns:

401 Unauthorized

The authentication dependency reports:

Invalid or missing API key.

Correct Authentication

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

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:

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:

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:

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:

$env:BINDAI_API_KEY = "your-secret-key"

A request can then be made with:

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:

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:

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:

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:

python -c "import secrets; print(secrets.token_urlsafe(32))"

The generated value can then be configured as:

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:

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:

User
 |
 v
Your Application
 |
 | Server-side API key
 v
BindAI API

rather than:

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:

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:

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:

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:

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:

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:

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:

POST /api/v1/runs

requires:

Authorization: Bearer your-secret-key

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

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:

Client
  |
  v
Invalid API Key
  |
  v
401 Unauthorized

Application failure:

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:

Authorization: Bearer your-secret-key

or any equivalent secret value.

Development vs Production

Local development can use a simple environment variable:

BINDAI_API_KEY=local-development-key

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

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:

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:

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:

curl http://localhost:8000/api/v1/projects

With authentication:

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:

BINDAI_API_KEY=your-secret-key

Client header:

Authorization: Bearer your-secret-key

Public endpoint:

GET /health

Protected endpoints include:

/api/v1/agents
/api/v1/workflows
/api/v1/projects
/api/v1/runs

For a normally configured API:

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.

​Authentication

​API Key Configuration

​Authorization Header

​Protected Endpoints

​Public Health Endpoint

​Authentication Flow

​Missing Authentication

​Invalid Authentication

​Correct Authentication

​Missing API Key Configuration

​PowerShell

​Docker

​Docker Compose

​Environment Configuration

​Secret Management

​Key Generation

​Key Rotation

​Client Security

​HTTPS

​Reverse Proxy Deployment

​Rate Limiting

​Authentication and Agent Access

​Authentication and Connections

​Authentication and Model Providers

​Authentication and Background Runs

​Authentication Errors

​Operational Logging

​Development vs Production

​Current v0.1 Authentication Model

​Future Authentication

​Security Checklist

​Testing Authentication

​API Authentication Summary