Skip to main content

​
Configure server authentication

Handler supports four auth types for configured servers:
  • bearer tokens
  • API keys
  • mTLS client certificates
  • OAuth2 client credentials
Add a server from the CLI with the matching auth flags, or define the auth block manually in servers.toml.

​
Bearer tokens

CLI: 
handler server add demo \
  --url https://agent.example.com \
  --bearer-env HANDLER_DEMO_TOKEN
TOML: 
[servers.demo]
url = "https://agent.example.com"

[servers.demo.auth]
type = "bearer"
env = "HANDLER_DEMO_TOKEN"
For one-off local setups you can also use a literal value, but environment variables are safer for anything shared.

​
API keys

CLI: 
handler server add demo \
  --url https://agent.example.com \
  --api-key-env HANDLER_DEMO_API_KEY
Handler sends API keys in X-API-Key by default. TOML with the default header: 
[servers.demo]
url = "https://agent.example.com"

[servers.demo.auth]
type = "api_key"
env = "HANDLER_DEMO_API_KEY"
TOML with a custom header: 
[servers.demo]
url = "https://agent.example.com"

[servers.demo.auth]
type = "api_key"
env = "HANDLER_DEMO_API_KEY"
header = "Authorization"

​
mTLS

CLI: 
handler server add demo \
  --url https://agent.example.com \
  --cert /path/to/client.crt \
  --key /path/to/client.key
TOML: 
[servers.demo]
url = "https://agent.example.com"

[servers.demo.auth]
type = "mtls"
cert = "/path/to/client.crt"
key = "/path/to/client.key"
ca_cert = "/path/to/ca.crt"
Handler checks that the certificate and key files exist before use, and verifies private key permissions.

​
OAuth2 client credentials

CLI: 
handler server add demo \
  --url https://agent.example.com \
  --oauth2-token-url https://auth.example.com/oauth/token \
  --oauth2-client-id-env HANDLER_CLIENT_ID \
  --oauth2-client-secret-env HANDLER_CLIENT_SECRET \
  --oauth2-scope read \
  --oauth2-scope write
TOML: 
[servers.demo]
url = "https://agent.example.com"

[servers.demo.auth]
type = "oauth2"
token_url = "https://auth.example.com/oauth/token"
client_id_env = "HANDLER_CLIENT_ID"
client_secret_env = "HANDLER_CLIENT_SECRET"
scopes = ["read", "write"]
Handler fetches the access token with the OAuth2 client credentials grant, applies it as a bearer token on requests, and refreshes it when it expires. Use an HTTPS token endpoint so client credentials are protected in transit.