Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt

Use this file to discover all available pages before exploring further.

Authentication in Hyperterse is tool-scoped and plugin-based. Each tool declares which plugin to use and supplies policy parameters. Auth runs after the tool is resolved and before input transforms or execution. Tools without an auth block are unauthenticated. There is no global auth middleware.

​
Configuration

Add an auth block to any tool config: 
auth:
  plugin: api_key
  policy:
    value: '{{ env.API_KEY }}'
The plugin field selects the auth strategy. The policy map passes plugin-specific parameters — typically credentials or validation rules.

​
Built-in plugins

Hyperterse ships with two plugins that cover the most common access patterns: The allow_all plugin unconditionally allows every request. Use for health checks, public tools, or development. 
auth:
  plugin: allow_all
The api_key plugin validates the X-API-Key HTTP header against a configured value. The expected key is resolved from policy.value (supports {{ env.VAR }} substitution) or falls back to the HYPERTERSE_API_KEY environment variable. 
auth:
  plugin: api_key
  policy:
    value: '{{ env.MY_SECRET_KEY }}'

​
Auth flow

When a tool runs, Hyperterse checks for an auth block on that tool. If you configured one, the plugin runs with the request context and policy map. Success continues the request; failure stops immediately with an authentication error.

​
Custom plugins

You can register custom auth plugins to implement strategies like JWT validation, OAuth bearer tokens, or IP allowlisting. Once registered, use the plugin name in tool configs just like the built-in ones: 
auth:
  plugin: jwt_bearer
  policy:
    issuer: 'https://auth.example.com'
    audience: 'my-service'
A plugin receives the request headers (extracted from the HTTP transport) and the policy map from the tool config. Return success to authorize, or an error to reject.

​
Key points

  • Auth is per-tool. Every tool that needs protection must declare it. There is no implicit inheritance.
  • No auth block means no authentication. The tool is accessible to anyone who can reach the endpoint.
  • Use environment variables for secrets. {{ env.VAR }} in policy values keeps credentials out of config files.
  • allow_all is not a security boundary. It exists for convenience — do not use it on production tools that access sensitive data.