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:

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)

config/users.yaml

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

API Keys

For programmatic access:

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.