Skip to main content
Authentication in Hyperterse is tool-scoped and plugin-based. Each tool declares which plugin to use and supplies policy parameters. The auth check runs as the second stage of the execution pipeline — after tool resolution, 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: allow_all — Unconditionally allows every request. Use for health checks, public tools, or development. 
auth:
  plugin: allow_all
api_key — 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 is invoked, the runtime checks whether the matched tool has an auth block. If present, the configured plugin is resolved and executed with the request context and policy map. A successful check allows the pipeline to continue. An error halts the pipeline immediately and returns 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.