> ## 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

> Tool-level authentication with built-in and custom plugins.

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:

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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:

```yaml theme={null}
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.