# Authentication: OAuth 2.1, API keys, multi-user

> ToolMesh authenticates AI clients via OAuth 2.1 PKCE, bcrypt API keys, or a single-user password. Documents config/users.yaml, DCR rate limits, identity flow.

Canonical: https://www.toolmesh.io/en/authentication/

ToolMesh provides a production-ready authentication system with multiple modes, from simple single-user setups to full multi-user OAuth.

## Authentication Modes

### Simple (Single-User)

Start quickly with environment variables:

```bash
TOOLMESH_AUTH_PASSWORD=changeme   # Single-user OAuth password
TOOLMESH_API_KEY=sk-my-key        # Static API key
```

### Multi-User OAuth 2.1

Full OAuth 2.1 with PKCE S256 for interactive login:

- Users defined in `config/users.yaml` (bcrypt-hashed passwords)
- Each user has: username, company, plan, roles
- Dynamic Client Registration (DCR), rate-limited (5/hour/IP)
- Redis/KeyDB for state persistence (tokens, auth codes, client registrations)

```yaml
# config/users.yaml
users:
  - username: alice
    password: "$2a$12$..."  # bcrypt hash
    company: acme
    plan: pro
    roles: [admin]
```

### API Keys

For programmatic access:

```yaml
# config/apikeys.yaml
keys:
  - key_hash: "$2a$12$..."  # bcrypt hash
    username: ci-bot
    company: acme
    plan: standard
    roles: [read]
    caller_id: github-actions
```

Each API key carries its own identity (user, company, plan, roles) that flows through the entire pipeline.

## Identity Flow

The authenticated identity flows through every step:

```
Authentication → CallerID → OpenFGA AuthZ → Credential Store → Audit Trail
```

This ensures full traceability: every tool call is attributed to a specific user, with a specific plan, from a specific client.

## Migration Path

Start with `TOOLMESH_AUTH_PASSWORD` for quick prototyping. When you need multiple users, switch to `users.yaml` — no architecture change required. The same pipeline handles both modes.