# Aperture configuration reference Last validated Jul 2, 2026 \[Missing snippet: aperture\_release\_note.mdx] > **Note:** > > During the beta testing period, Aperture by Tailscale is available at no additional cost across [all Tailscale plans][co-pricing], and each instance includes six free users. Request access at [`aperture.tailscale.com`][xt-aperture-signup]. Contact Tailscale for pricing if you need more than six users. [Aperture by Tailscale][kb-aperture] uses a JSON configuration to specify LLM providers, access control policies, and optional integrations. The Aperture configuration controls which models are available, how requests authenticate with upstream providers, and who can access what. Admins can edit the configuration on the **Administration** > **Configuration** page of the [Aperture admin dashboard][kb-aperture-dashboard-admin], or use the visual editors for individual sections such as **Providers** and **Grants**, under the same **Administration** group. This topic is part of the [Aperture reference][kb-aperture-reference] documentation. ## Minimal configuration A typical minimal configuration includes at least one provider with a base URL and at least one model. If you use MCP servers or connectors exclusively, you can omit providers. The following example shows a minimal configuration with a single provider: ```json { "providers": { "anthropic": { "baseurl": "https://api.anthropic.com", "apikey": "", "models": [ "claude-sonnet-4-6", "claude-opus-4-8", ], "authorization": "x-api-key", "compatibility": { "anthropic_messages": true, } } } } ``` If you omit `apikey`, Aperture continues to run. Most providers require an API key for authentication, so add one unless your provider handles authentication differently. > **Note:** > > The `apikey` field takes an API key from the provider's developer platform, which is the standard way to authenticate a provider. Consumer and business subscription plans such as [Claude Pro or Claude Max][xt-anthropic-plans], [ChatGPT Plus, Pro, or Team][xt-openai-plans], and [Gemini Advanced][xt-gemini-plans] issue OAuth tokens rather than API keys, so there is no key to put in this field. To use a subscription plan, configure the provider with `auth_mode: "passthrough"` and let each client forward its own credential to the upstream. For more information, refer to [Set up passthrough mode][kb-use-passthrough-mode]. ## Default configuration New Aperture instances use a default configuration that includes OpenAI and Anthropic providers with common models. The default grants all users access to all models. The following shows the default configuration: ```json { "grants": [ // Grant admin access (permission to see the settings and all other // users in the dashboard). { "src": [ // Explicitly identify certain users by their Tailscale login. "example-user@example.com", // Grant admin access to everyone by default. // Remove this after you've configured explicit admin // access for yourself. // BE CAREFUL! If you remove this without granting explicit // admin access to yourself, you'll lose your ability // to edit this file. "*", ], "app": { "tailscale.com/cap/aperture": [ { "role": "admin" }, ], }, }, // Every user who can access Aperture gets at least user-level access. // Remove this and Aperture denies access entirely by default. // Admin access in a separate grant takes precedence over this section. { "src": ["*"], "app": { "tailscale.com/cap/aperture": [ { "role": "user" }, ], }, }, // Default: allow all users to access all models from all providers. // Without this grant, users can't access any models (deny by default). { "src": ["*"], "app": { "tailscale.com/cap/aperture": [ { "models": "**" }, ], }, }, // This example hook sends traffic to Oso if it matches certain // parameters. Configure Oso in the "hooks" section for this to work. { "src": [ // No users by default. Try "*" to capture everyone's traffic. ], "app": { "tailscale.com/cap/aperture": [ { "send_hooks": [ { "name": "oso", // Capturing only tool calls "events": ["tool_call_entire_request"], "send": ["user_message", "tools", "request_body", "response_body"], }, ], }, ], }, }, ], // Configure your LLM backends here. // Fill your API keys in below to share these providers with your team. // There's no limit to the number of providers you can configure. "providers": { "openai": { "baseurl": "https://api.openai.com", "name": "OpenAI", "apikey": "", "models": [ "gpt-5.5", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4", "gpt-5.3-codex", ], "compatibility": { "openai_chat": true, "openai_responses": true, "anthropic_messages": false, }, }, "anthropic": { "baseurl": "https://api.anthropic.com", "name": "Anthropic", "apikey": "", "models": [ "claude-sonnet-4-6", "claude-haiku-4-5", "claude-haiku-4-5-20251001", "claude-opus-4-8", ], "compatibility": { "openai_chat": false, "openai_responses": false, "anthropic_messages": true, }, }, }, // Hooks are configured API endpoints that Aperture calls under certain // conditions. The conditions themselves are configured in the // "grants" section. "hooks": { "oso": { "url": "https://api.osohq.com/api/agents/v1/model-request", "apikey": "", }, }, } ``` ## Configuration reference The Aperture configuration contains several top-level sections that control different aspects of Aperture's behavior. The following table describes the available top-level sections: | Section | Required | Description | | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `providers` | No | Map of LLM provider configurations. Tailscale recommends at least one provider or MCP server/connector. | | `grants` | No | Access control policies for users, models, and quotas. Uses the Tailscale grant structure. | | `quotas` | No | Dollar-based spending limits using token buckets. | | `hooks` | No | Webhook endpoint configurations. | | `exporters` | No | LLM session log export configuration. Supports S3-compatible storage. | | `database` | No | Data storage settings, including capture retention policies. | | `connectors` | No | Outbound integrations (MCP servers and HTTP APIs) with authentication. | | `auto_cost_basis` | No | Boolean (default `true`). When `true`, Aperture infers `cost_basis` from a provider's compatibility flags when no explicit `cost_basis` is set. Set to `false` to disable auto-inference, so only providers with an explicit `cost_basis` produce cost estimates. | | `flags` | No | Experimental feature flags. Each key is a flag ID containing a `value` boolean. Refer to the [flags reference][ar-flags-section] for available flags and what they control. | | `mcp` | No | Deprecated MCP server proxying configuration. Use `connectors` instead. | | `temp_grants` | No | Deprecated access control syntax. Use `grants` instead. | ### `providers` The `providers` section specifies the LLM providers to which Aperture routes requests. A unique string key identifies each provider. The following example shows the basic structure: ```json { "providers": { "openai": { ... }, "anthropic": { ... }, "private": { ... } } } ``` Each provider configuration accepts the following fields: | Field | Type | Required | Default | Description | | ---------------- | ------ | -------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `baseurl` | string | Yes | N/A | Base URL for the provider's API. | | `models` | array | Yes | N/A | List of model IDs available from this provider. | | `apikey` | string | No | `""` | API key for authentication. | | `authorization` | string | No | `"bearer"` | Authorization header type. | | `auth_mode` | string | No | `""` (override) | Source of the upstream credential. One of `""`/`override` (inject the configured `apikey`), `passthrough` (forward the client's credential, fall back to `apikey`), or `none` (send no credential). Refer to [`auth_mode`][ar-auth-mode]. | | `name` | string | No | `""` | Display name for the UI. | | `description` | string | No | `""` | Description shown in the UI. | | `compatibility` | object | No | `openai_chat` enabled, all others disabled | API compatibility flags. Refer to the [provider compatibility reference][kb-aperture-provider-compatibility] for details. | | `cost_basis` | string | No | Auto-inferred | Override the pricing service used for cost estimation. Refer to the [provider compatibility reference][kb-aperture-provider-compatibility] for valid values. | | `preference` | int | No | `0` | Routing priority when a model is available from multiple providers. Higher value wins. | | `disabled` | bool | No | `false` | Deactivates the provider without removing its configuration. Disabled providers are excluded from routing and `/v1/models`. | | `add_headers` | array | No | `[]` | Custom headers added to every upstream request for this provider. Each entry uses `"Header-Name: value"` format. | | `model_cost_map` | array | No | `[]` | Map unknown model names to known models for pricing. Refer to [model cost map][kb-aperture-provider-compatibility-model-cost-map]. | \[Missing snippet: aperture\_provider\_auth\_note.mdx] #### `auth_mode` The `auth_mode` field controls how Aperture obtains the credential it sends to the upstream provider. It does not affect routing, model selection, or the authorization header format (use `authorization` to configure that). Valid values are: | Value | Behavior | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `""` (default) | Inject the configured `apikey` on every request. | | `override` | Explicit form of the default. Inject the configured `apikey`; requires a non-empty `apikey`, or the configuration fails to save. | | `passthrough` | Forward the client's own `Authorization` or `x-api-key` header to the upstream unchanged. Fall back to the configured `apikey` only when the client sends no credential. | | `none` | Strip all upstream credentials, for providers that need none. | A `passthrough` provider with no configured `apikey` is passthrough-only. It serves only requests that carry a client credential. Its models still appear in the `/v1/models` endpoint, but Aperture hides them from the built-in chat UI, because server-originated chat requests carry no client credential. Configure a fallback `apikey` if you want the models available in the chat UI. For a full walkthrough, including using subscription-plan OAuth tokens, refer to [Set up passthrough mode][kb-use-passthrough-mode]. #### How Aperture builds upstream URLs Aperture appends the full incoming request path to the provider's `baseurl` to construct the upstream URL. For example, if `baseurl` is `https://api.openai.com` and a client sends `POST /v1/chat/completions`, the upstream URL is `https://api.openai.com/v1/chat/completions`. Set `baseurl` to the provider's API root. The `/v1` segment belongs in the request path, not in `baseurl`. Aperture does not strip `/v1` from `baseurl` before appending the path. > **Warning:** > > If `baseurl` includes `/v1`, the upstream URL contains `/v1/v1/...`, which causes HTTP 405 errors from the upstream provider. This is the most common provider setup mistake. Refer to [troubleshooting HTTP 405 errors][kb-aperture-troubleshoot-405] for resolution steps. **Exceptions**: Amazon Bedrock requests have the `/bedrock` prefix stripped before forwarding. Vertex AI requests have auto-fill placeholders replaced in the path. All other providers receive the incoming path unchanged. For the correct `baseurl` for each supported provider, refer to the [provider compatibility matrix][kb-aperture-provider-compatibility]. #### Model names Aperture does not verify model names in the provider configuration. Aperture sends names directly to the upstream provider as-is. If the upstream provider supports wildcards or prefixes in model names, Aperture supports them too. For valid model names, refer to the provider's own documentation (for example, [Anthropic models][xt-anthropic-models] or [OpenAI models][xt-openai-models]) and the Aperture [provider setup guides][kb-aperture-set-up-providers]. For example, Anthropic supports model name prefixes in their API. You can use a prefix like `claude-opus*` in your `models` list, which matches `claude-opus`, `claude-opus-4-6`, `claude-opus-4-7`, and any future `claude-opus` variant. ```json "models": ["claude-opus*", "claude-sonnet-4-6"] ``` #### Authorization types Different providers require different authorization header formats. The `authorization` field supports `bearer` (default, used by OpenAI and most providers), `x-api-key` (Anthropic), and `x-goog-api-key` (Google Gemini). For the full authorization types table and provider-specific details, refer to the [provider compatibility reference][kb-aperture-provider-compatibility]. #### Provider compatibility The `compatibility` object specifies which API formats the provider supports. This determines which endpoints Aperture exposes for the provider's models. Flags include `openai_chat` (default enabled), `openai_responses`, `anthropic_messages`, `gemini_generate_content`, `bedrock_model_invoke`, and others. For the complete compatibility flags table, provider matrix, and configuration examples for each provider, refer to the [provider compatibility reference][kb-aperture-provider-compatibility]. #### Provider examples For complete configuration examples for each supported provider (OpenAI, Anthropic, Google Gemini, Vertex AI, Amazon Bedrock, OpenRouter, and self-hosted LLMs), refer to the [provider compatibility reference][kb-aperture-provider-compatibility]. ### Pricing and cost estimation Aperture estimates the dollar cost of every LLM request. Cost estimates power quotas, hook metadata, and the per-model pricing shown in the Aperture dashboard. Aperture auto-infers pricing for known providers based on compatibility flags, but you can override this with the `cost_basis` and `model_cost_map` provider fields. For the full list of `cost_basis` values, model cost mapping syntax, and per-provider pricing details, refer to the [provider compatibility reference][kb-aperture-provider-compatibility]. Aperture surfaces cost data in several places: * **Models** page of the Aperture dashboard: Each model shows per-million-token pricing (input/output) with a tooltip that includes cache, reasoning, image, and web search rates. * **CSV export**: The **Usage Overview** page's **Download CSV** button (admin only) exports usage data including token counts per model, user, and date. * **Hooks**: Include `"estimated_cost"` in a hook's `send` array to receive dollar cost, cost basis, and token usage with every hook call. Refer to [hook send types][ar-hook-send-types] for details. ### `grants` The `grants` section specifies access control policies that determine which users can access which models, what hooks fire, and which quotas apply. Grants use the [Tailscale grant structure][kb-tailscale-grants] with capabilities scoped under `"tailscale.com/cap/aperture"`. Aperture is deny-by-default: without a matching grant, a user cannot access any models. For step-by-step instructions on configuring access, refer to [grant access to models][kb-aperture-grant-model-access], [grant access to MCP tools][kb-aperture-grant-mcp-tool-access], and [set up admin access][kb-aperture-set-up-admin-access]. > **Note:** > > The `grants` section replaces the deprecated `temp_grants` syntax with a new structure. The `temp_grants` syntax still works but Tailscale does not recommend it for new configurations. Configure grants in the Aperture dashboard (on the **Administration** > **Grants** page, or the **Administration** > **Configuration** editor) or through the API (`PUT http:///api/config`). #### Basic structure A grant specifies a source (`src`) and a set of app capabilities: ```json "grants": [ { "src": ["*"], // who this grant applies to "app": { "tailscale.com/cap/aperture": [ // array of individual capabilities { "models": "**" }, // allow access to all models ], }, }, ] ``` \[Missing snippet: aperture\_grant\_dst\_note.mdx] #### Source match (`src`) The `src` field determines which users a grant applies to: * `"*"`: Matches everyone. * `"alice@example.com"`: Matches a specific Tailscale login name. * `"group:engineering"`: Matches members of a Tailscale group or SCIM group. Requires [visible groups][kb-aperture-visible-groups] enabled for the Aperture device. * `"engineering@example.com"`: Matches members of a SCIM group (by email). Requires [visible groups][kb-aperture-visible-groups] enabled for the Aperture device. * `"tag:ci-runner"`: Matches a tagged device. \[Missing snippet: contact\_account\_manager.mdx] #### Model access Each `models` field accepts a single glob pattern using fully-qualified `provider/model` format. To match multiple providers, use separate grant entries. | Pattern | Matches | | :------------------- | :----------------------------------------------------------- | | `"**"` | All models from all providers | | `"anthropic/**"` | All Anthropic models | | `"openai/gpt-5.5"` | Exactly `openai/gpt-5.5` | | `"*/claude-sonnet*"` | Any `claude-sonnet*` model from any single provider | | `"aperture-*/**"` | Any model from a provider whose name starts with `aperture-` | `*` matches any characters within a single path segment (it does not cross `/`). `**` matches zero or more segments. A grant with no `models` field is "floating," meaning it applies globally (useful for hooks and quotas that apply regardless of model). #### Role assignment Roles determine a user's permission level: ```json { "role": "admin" } // full admin access { "role": "user" } // standard user access ``` Without a role grant, the user cannot access Aperture. If multiple grants match a given user, the highest-permissioned role (admin) wins. #### Connector access \[Missing snippet: aperture\_mcp\_experimental\_note.mdx] Grant access to connectors using the `connectors` field, which accepts an array of fully-qualified name (FQN) glob patterns in `"connectorID/category/resource"` format: ```json { "connectors": ["aperture/**"], // all capabilities from the "aperture" connector } ``` More specific patterns: ```json { "connectors": [ "github/proxy", // proxy access to the "github" HTTP connector "docs/tools/*", // all tools from the "docs" MCP connector "snowflake/**", // everything from "snowflake" ], } ``` The `connectors` field uses the same `*` / `**` glob syntax as `models`. The `category` segment is one of `tools`, `resources`, `templates` (MCP connectors), or `proxy` (HTTP connectors). A pattern with an unrecognized category silently never matches, so it grants no access. For the per-category breakdown, refer to the [connectors reference][kb-aperture-connectors-reference]. > **Note:** > > The `mcp_tools`, `mcp_resources`, and `mcp_templates` fields are deprecated. They still work for backward compatibility, but new configurations should use the `connectors` field instead. #### Additional capability fields Each capability object in the `tailscale.com/cap/aperture` array can also include these fields: | Field | Type | Description | | ------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connectors` | `[]string` | Array of FQN glob patterns for connector access (for example, `["aperture/**"]`, `["github/proxy"]`). Uses the same `*` / `**` glob syntax as `models`. | | `add_headers` | array | Custom headers prepended to upstream requests when this grant matches. Each entry uses `"Header-Name: value"` format. | | `enable_chat_ui` | bool | Controls access to the chat UI feature. The chat UI is available by default. Set to `false` to disable it for a grant. | | `read_metrics` | bool | Grants access to the `/metrics` Prometheus endpoint. | | `set_cors` | bool | Enables CORS response header injection for this grant. Requires a non-empty `cors_paths` list. | | `cors_paths` | array | URL path glob patterns that activate CORS headers (for example, `["/v1/**", "/bedrock/**"]`). Uses the same glob syntax as `models` but applied to URL paths. An empty list disables CORS even when `set_cors` is `true`. | | `Access-Control-Allow-Origin` | string | Value for the `Access-Control-Allow-Origin` response header. | | `Access-Control-Allow-Methods` | string | Value for the `Access-Control-Allow-Methods` response header. | | `Access-Control-Allow-Headers` | string | Value for the `Access-Control-Allow-Headers` response header. | #### CORS headers CORS header injection lets browser-based clients access Aperture's LLM endpoints directly. You configure CORS per-grant, so different users can have different CORS policies (or none). A CORS capability is separate from model access. The user still requires a `models` grant (in the same or a different grant entry) to access models. Both `set_cors: true` and a non-empty `cors_paths` list are required for CORS headers to be set. The `cors_paths` field uses the same glob syntax as `models` but matches against URL paths (paths must begin with `/`). Aperture automatically handles `OPTIONS` preflight requests by returning `200 OK` with the configured headers when a CORS grant matches. ```json { "src": ["browser-app@example.com"], "app": { "tailscale.com/cap/aperture": [ { "set_cors": true, "cors_paths": ["/v1/**", "/bedrock/**"], "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "POST, OPTIONS", "Access-Control-Allow-Headers": "Content-Type, Authorization" } ] } } ``` > **Warning:** > > Using `Access-Control-Allow-Origin: *` lets any website make requests to Aperture on behalf of the matched user. Restrict the origin to specific domains when possible (for example, `"https://app.example.com"`). #### Custom app capabilities Grants can include capability keys beyond `tailscale.com/cap/aperture`. Aperture passes these through to hooks when you include the `"grants"` send type: ```json { "src": ["admin@example.com"], "app": { "tailscale.com/cap/aperture": [ { "role": "admin" }, { "models": "**" }, ], // Custom capability: forwarded to hooks via "grants" send type "mycompany.com/cap/policy": [ { "tier": "enterprise", "department": "engineering" }, ], }, }, ``` When a hook includes `"grants"` in its `send` array, these custom capabilities appear in the hook metadata. External systems can use these capabilities to make authorization decisions. ### `quotas` The `quotas` section specifies dollar-based spending limits using token buckets. Each bucket has a capacity (maximum balance) and a refill rate. When a request's estimated cost would bring a bucket below zero, Aperture rejects the request with HTTP 429. For step-by-step instructions, refer to [set per-user spending limits][kb-aperture-set-per-user-spending-limits] and [set a team-wide budget][kb-aperture-set-team-budget]. To check and refill budgets, refer to [check and refill budgets][kb-aperture-monitor-quota-balances]. ```json "quotas": { // Per-user daily budget: refills $5/day, can burst up to $10 "daily:": { "capacity": "$10.00", "rate": "$5.00/day", "on_exceed": "reject", }, // Shared pool across all users who reference it "eng-team-pool": { "capacity": "$100.00", "rate": "$100.00/day", "on_exceed": "reject", }, // Per-user limit for expensive models "opus:": { "capacity": "$5.00", "rate": "$2.50/day", "on_exceed": "reject", }, } ``` Each quota accepts the following fields: | Field | Format | Description | | :---------- | :------------------- | :---------------------------------------------------------------------------------------------------------- | | `capacity` | `"$"` | Maximum balance the bucket can hold (must be greater than zero). Also the starting balance for new buckets. | | `rate` | `"$/"` | How fast the bucket refills. Units: `min`, `hour`, `day`, `week`, `month` (30 days). | | `on_exceed` | `"reject"` | Action when a request would bring the bucket below zero. The supported value is `"reject"` (HTTP 429). | Quota configuration uses dollar strings (for example, `"$10.00"`). [Hook payloads][ar-hooks] represent the same values in nanodollars (1 dollar = 1,000,000,000 nanodollars). #### Template variables Quota names can include template variables that expand at request time: | Template | Expands to | Example | | :------- | :------------------------------------------------------------------------------------------ | :-------------------------------------------------- | | `` | Caller's Tailscale login name or tag combination | `daily:` expands to `daily:alice@example.com` | | `` | Caller's node ID (a distinct quota for each node, even if nodes share the same user or tag) | `device:` expands to `device:n8f3a2c9d1CNTRL` | Quotas without a template variable (for example, `eng-team-pool`) create a single shared bucket. #### Attach quotas to grants Quotas take effect only when attached to grants. A quota specified in the `quotas` section does nothing until a grant references it. When a request matches a grant, Aperture charges all quotas listed in that grant at the same time: ```json "grants": [ { "src": ["*"], "app": { "tailscale.com/cap/aperture": [ { "models": "**", "quotas": [ {"bucket": "daily:"}, {"bucket": "eng-team-pool"}, ], }, ], }, }, ] ``` #### How multiple quotas interact When a grant references multiple quota buckets, all buckets must have a positive balance for the request to proceed. If any single bucket is exhausted, Aperture rejects the request, even if other buckets have remaining balance. After the response completes, Aperture deducts the estimated cost from every referenced bucket at the same time. A request can match multiple grants, each with their own quotas. Aperture collects and enforces all matching quotas together. #### Bucket lifecycle Aperture persists quota bucket balances. When you update a quota definition (for example, changing the capacity or refill rate), Aperture adjusts existing balances to match the new settings and caps each balance at the new capacity. Aperture removes buckets whose quota definitions you delete from the configuration. > **Note:** > > If you reduce a bucket's `capacity`, Aperture caps any existing balance above the new capacity to the new value. You cannot recover the excess. #### Quota examples The following examples show common quota configurations. ##### Per-user quota Each user gets their own bucket with independent capacity and refill rate: ```json "quotas": { "daily:": { "capacity": "$10.00", "rate": "$5.00/day", "on_exceed": "reject", }, }, "grants": [ { "src": ["*"], "app": { "tailscale.com/cap/aperture": [ { "role": "user" }, { "models": "**", "quotas": [{"bucket": "daily:"}] }, ], }, }, ] ``` This creates a separate bucket for each user (for example, `daily:alice@example.com`, `daily:bob@example.com`), each with $10 capacity and a $5/day refill. ##### Quota scoped to specific models Apply a quota only when the request targets specific models: ```json "quotas": { "opus:": { "capacity": "$5.00", "rate": "$2.50/day", "on_exceed": "reject", }, }, "grants": [ { "src": ["*"], "app": { "tailscale.com/cap/aperture": [ // General access, no quota { "models": "**" }, // Additional quota for Opus models only { "models": "*/claude-opus*", "quotas": [{"bucket": "opus:"}], }, ], }, }, ] ``` The `opus:` quota applies only when the request targets an Opus model. Other models are unmetered. ##### Combine per-user and shared quotas Charge each request against both a personal budget and a shared team pool: ```json "quotas": { "daily:": { "capacity": "$10.00", "rate": "$5.00/day", "on_exceed": "reject", }, "team-monthly": { "capacity": "$500.00", "rate": "$500.00/month", "on_exceed": "reject", }, }, "grants": [ { "src": ["*"], "app": { "tailscale.com/cap/aperture": [ { "role": "user" }, { "models": "**", "quotas": [ {"bucket": "daily:"}, {"bucket": "team-monthly"}, ], }, ], }, }, ] ``` In this example, every request deducts from both the user's daily bucket and the shared team-monthly bucket. Aperture blocks a user who exhausts either bucket. ### `hooks` The `hooks` section specifies webhook endpoints that Aperture calls when conditions match. A unique string key identifies each hook, and grants reference this key. For step-by-step setup, refer to [build a custom webhook][kb-aperture-build-custom-webhook]. For integration-specific guides, refer to [integrate Oso with Aperture][kb-aperture-integrate-oso] or [integrate Cerbos with Aperture][kb-aperture-integrate-cerbos]. The following example shows the hooks configuration: ```json { "hooks": { "oso": { "url": "https://api.osohq.com/api/agents/v1/model-request", "apikey": "", "timeout": "10s" }, "my-webhook": { "url": "https://example.com/webhook", "apikey": "" } } } ``` Each hook configuration accepts the following fields: | Field | Type | Required | Default | Description | | --------------- | ------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `url` | string | Yes | N/A | HTTP or HTTPS endpoint to POST hook data to. | | `apikey` | string | No | `""` | API key that Aperture sends to the hook endpoint using the method specified by `authorization`. | | `authorization` | string | No | `"bearer"` | How Aperture sends the API key. Supports the same values as provider authorization: `bearer`, `x-api-key`, `x-goog-api-key`, `hec`, `cf-aig-authorization`. | | `timeout` | string | No | `"5s"` | Maximum duration to wait for the hook to respond. | | `disabled` | boolean | No | `false` | Skips this hook when Aperture would otherwise call it. Useful for temporarily disabling a hook without removing its configuration. | | `fail_policy` | string | No | `"fail_open"` | Behavior when the hook is unreachable or returns an error. `fail_open` lets the request proceed. `fail_closed` blocks the request. Applies to `pre_request` hooks only. | | `preference` | int | No | `0` | Execution priority among stacked hooks. Higher values run first. Hooks with equal preference run in alphabetical order by key. Not related to the provider-level `preference` field. | The `timeout` field accepts Go duration strings such as `5s`, `30s`, or `1m`. Set to `0` to disable the timeout. The `send_hooks` entries in the `grants` section trigger hooks. A hook specified here does nothing until a grant references it. ### Hook grants To trigger a hook, add a `send_hooks` entry to a capability in the `grants` section. Hook grants specify which requests trigger the hook and what data to send. ```json { "grants": [ { "src": ["*"], "app": { "tailscale.com/cap/aperture": [ { "models": "**", "send_hooks": [ { "name": "oso", "events": ["tool_call_entire_request"], "send": ["tools", "user_message", "request_body", "response_body"], }, ], }, ], }, }, ] } ``` Each `send_hooks` entry contains the following fields: | Field | Type | Description | | -------- | ------ | ------------------------------------------------------------------ | | `name` | string | Key referencing a hook specified in the top-level `hooks` section. | | `events` | array | Event types that trigger the hook. | | `send` | array | List of data types to include in the hook payload. | #### Hook events | Event | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `pre_request` | Fires before the provider call. Synchronous: Aperture waits for the hook response. The hook can allow, block, or modify the request. | | `entire_request` | Fires for every completed request. Asynchronous: does not affect the request or response. | | `tool_call_entire_request` | Fires once after the response completes if any message in the response contained tool calls. Asynchronous: does not affect the request or response. | #### Hook send types The `send` array specifies which data to include in the POST payload sent to the hook endpoint: | Field | Description | | ---------------- | --------------------------------------------------------------------------- | | `tools` | Array of tool calls extracted from the response. | | `request_body` | The original request body sent to the LLM. | | `user_message` | The user's message from the request. | | `response_body` | The reconstructed response body JSON. | | `raw_responses` | Array of raw SSE messages (for streaming) or single response object. | | `estimated_cost` | Dollar cost estimate, pricing basis, and token usage breakdown. | | `grants` | Non-Aperture app capabilities from the user's grants (custom capabilities). | | `quotas` | Current state of all quota buckets that applied to this request. | #### `estimated_cost` Includes the dollar cost estimate, the pricing basis used, and a token usage breakdown. These fields appear inside the `metadata` object of the hook payload: ```json { "models": "**", "send_hooks": [ { "name": "audit", "events": ["tool_call_entire_request"], "send": ["tools", "estimated_cost"], }, ], } ``` The hook receives the cost data inside `metadata`: ```json { "metadata": { "login_name": "user@example.com", "...": "...", "estimated_cost": { "dollars": 0.0342, "cost_basis": "anthropic/claude-sonnet-4-6", "usage": { "input_tokens": 1500, "output_tokens": 800, "cached_tokens": 200, "reasoning_tokens": 0 } } }, "tool_calls": [...] } ``` #### `grants` Includes any non-Aperture app capabilities from the user's grants. This lets external systems (policy engines, audit logs) access custom capabilities attached to the user. The `grants` data appears inside the `metadata` object: ```json { "src": ["alice@example.com"], "app": { "tailscale.com/cap/aperture": [ { "models": "**" }, { "send_hooks": [ { "name": "policy-engine", "events": ["entire_request"], "send": ["estimated_cost", "grants"], }, ], }, ], "mycompany.com/cap/policy": [ {"tier": "enterprise", "max_context": 200000}, ], }, } ``` The hook receives the custom capabilities inside `metadata`: ```json { "metadata": { "login_name": "alice@example.com", "...": "...", "grants": { "mycompany.com/cap/policy": [ {"tier": "enterprise", "max_context": 200000} ] }, "estimated_cost": { "..." } } } ``` #### `quotas` Includes the current state of all quota buckets that applied to the request. The `quotas` data appears inside the `metadata` object: ```json "send": ["tools", "quotas"] ``` The hook receives the bucket state inside `metadata`: ```json { "metadata": { "login_name": "alice@example.com", "...": "...", "quotas": { "daily:alice@example.com": { "current": 7250000000, "capacity": 10000000000, "rate": "$5.00/day" } } } } ``` Values for `current` and `capacity` are in nanodollars (1 dollar = 1,000,000,000 nanodollars). Every hook call automatically includes a `metadata` object with request context: ```json { "metadata": { "login_name": "user@example.com", "user_agent": "curl/8.0", "url": "/v1/chat/completions", "model": "gpt-5.5", "provider": "openai", "tailnet_name": "example.com", "stable_node_id": "n12345", "request_id": "abc123", "session_id": "oacc_1a2b3c4d5e6f7890" } } ``` #### Hook grant example The following example sends tool call data and cost estimates to an audit service for all requests from a specific user: ```json { "grants": [ { "src": ["developer@company.com"], "app": { "tailscale.com/cap/aperture": [ { "models": "anthropic/**", "send_hooks": [ { "name": "my-webhook", "events": ["tool_call_entire_request"], "send": ["tools", "user_message", "estimated_cost"], }, ], }, { "models": "openai/**", "send_hooks": [ { "name": "my-webhook", "events": ["tool_call_entire_request"], "send": ["tools", "user_message", "estimated_cost"], }, ], }, ], }, }, ] } ``` \[Missing snippet: aperture\_grant\_dst\_note.mdx] #### Hook response format For `pre_request` hooks, the hook endpoint must return a JSON response that tells Aperture how to handle the request. Asynchronous hooks (`entire_request`, `tool_call_entire_request`) ignore the response body. Any valid JSON (including `{}`) is sufficient. The response contains the following fields: | Field | Type | Required | Default | Description | | -------------- | ------ | --------------------- | -------------------------------- | -------------------------------------------------------------------- | | `action` | string | Yes | N/A | How to handle the request. Valid values: `allow`, `block`, `modify`. | | `status_code` | int | No | `403` | HTTP status code returned to the client. Applies to `block` only. | | `message` | string | No | `"request blocked by guardrail"` | Error message returned to the client. Applies to `block` only. | | `request_body` | object | Required for `modify` | N/A | Replacement request body forwarded to the provider. | The three actions: * **`allow`**: The request proceeds unchanged. Aperture ignores other fields. * **`block`**: Aperture rejects the request without forwarding it to the provider. The client receives a format-specific error response with the `status_code` and `message`. * **`modify`**: Aperture replaces the forwarded request body with the `request_body` from the hook response and continues to the provider. The `request_body` must be a JSON object. If the hook returns a non-object, Aperture treats the response as `allow`. When a hook blocks a request, the client receives an error envelope that matches the API format of the original request: | API format | Error envelope | | ----------------------- | --------------------------------------------------------------------------------- | | OpenAI Chat / Responses | `{"error": {"message": "...", "type": "guardrail_blocked"}}` | | Anthropic Messages | `{"type": "error", "error": {"type": "invalid_request_error", "message": "..."}}` | | Gemini / Vertex | `{"error": {"code": ..., "message": "...", "status": "PERMISSION_DENIED"}}` | | Bedrock Invoke/Converse | Header `x-amzn-ErrorType: AccessDeniedException`. Body `{"message": "..."}` | #### Hook chains When multiple `pre_request` hooks match a request, Aperture calls them sequentially in a deterministic order. **Ordering**: Aperture sorts hooks by descending `preference`, with alphabetical order by hook key as the tiebreak. A hook with `preference: 10` runs before one with `preference: 0` (the default). Hooks with equal preference run alphabetically: `audit-a` runs before `audit-z`. **Chain execution**: * **`allow`** is a no-op. The chain proceeds to the next hook with the current request body. * **`modify`** rewrites the request body in place. The next hook in the chain receives the modified body, not the original. * **`block`** terminates the chain immediately. Hooks later in the chain do not run, and the client receives the block response. If a hook in the chain modifies the request and a later hook blocks it, the block takes effect and Aperture does not forward the modification to the provider. The blocking hook does receive the modified body when making its decision. To enforce a block independently of earlier modifications, give the blocking hook a higher `preference` so it runs first. **Failure handling**: When a `pre_request` hook fails (unreachable, timed out, non-2xx response, or unparseable body), the `fail_policy` on the hook definition controls what happens. `fail_open` proceeds to the next hook in the chain. `fail_closed` blocks the request with HTTP 503 and no subsequent hooks run. Asynchronous hooks always fail open: if the hook errors, the request still proceeds. ### `exporters` The `exporters` section configures periodic export of LLM session logs to external storage. Aperture supports exporting to S3-compatible storage, such as Amazon S3 and Google Cloud Storage. For step-by-step setup, refer to [export usage data to S3][kb-aperture-export-s3]. The following example shows the exporters configuration: ```json { "exporters": { "s3": { "endpoint": "https://your-s3-compatible-endpoint.url", "bucket_name": "aperture-exports", "region": "us-east-1", "prefix": "prod", "access_key_id": "", "access_secret": "", "every": 3600, "limit": 1000 } } } ``` Setting `bucket_name` to a non-empty value enables the S3 exporter. Each S3 exporter configuration accepts the following fields: | Field | Type | Required | Default | Description | | --------------- | ------ | ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `endpoint` | string | No | `""` | HTTP endpoint for an S3-compatible API. Required for non-AWS services such as GCS. Omit for Amazon S3, where Aperture infers the endpoint from `region`. | | `bucket_name` | string | Conditional | `null` | Name of the S3 bucket to upload exports to. Setting this field to a non-empty value enables the S3 exporter. | | `region` | string | No | `"us-east-1"` | AWS region for the bucket. Required even for non-AWS endpoints because the AWS SDK validates this field. | | `prefix` | string | No | `""` | Path prefix for new S3 objects. Must not end with `/`. | | `access_key_id` | string | Conditional | `null` | AWS access key ID used to authenticate. Required and must be non-empty when `bucket_name` is set and static credentials are used. | | `access_secret` | string | Conditional | `null` | Secret key used with `access_key_id` to authenticate. Required and must be non-empty when `access_key_id` is set. | | `every` | int | No | `3600` | Number of seconds to wait after the last export before starting another. Default is one hour. | | `limit` | int | No | `1000` | Maximum number of records per export. Aperture caps this value at `10000` and reduces higher values without a warning. | ### `connectors` The `connectors` section configures outbound integrations, including authenticated MCP servers and HTTP API proxies. Connectors replace the deprecated `mcp.servers` syntax and add support for authenticated connections and multiple protocols. \[Missing snippet: aperture\_mcp\_experimental\_note.mdx] > **Note:** > > The `connectors` section requires the `connectors` feature flag. Enable it by adding `"flags": {"connectors": {"value": true}}` to your configuration. Refer to [flags][ar-flags-section] for details on enabling feature flags. ```json { "connectors": { "servers": { "tailnetMCP": { "protocol": "mcp", "url": "http://mcp-server.example.ts.net:8080/v1/mcp" }, "github": { "protocol": "http", "url": "https://api.github.com", "description": "GitHub REST API (read-only)", "auth": { "type": "bearer_token", "secret": "github_pat_example" } } } } } ``` #### `connectors` fields | Field | Type | Default | Description | | --------- | ---- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `servers` | map | `{}` | Map of connector ID to server configuration. The map key is the connector ID, which becomes the name prefix for tools (`connectorID_toolname`), resources (`connectorID-uri`), and resource templates (`connectorID-uriTemplate`). | #### `servers` fields Each entry in the `servers` map accepts the following fields: | Field | Type | Required | Default | Description | | ------------- | -------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `protocol` | string | Yes | N/A | How Aperture communicates with the upstream. One of `"mcp"` or `"http"`. | | `url` | string | No | N/A | Endpoint URL of the upstream server. Aperture warns if `url` is missing but still loads the configuration. | | `provider` | string | No | `"Custom"` | Provider identifier. Set automatically when using a verified connector from the registry (for example, `"Salesforce"`, `"Atlassian"`, `"Slack"`). Controls whether the connector appears in the "verified" or "custom" category in the dashboard. | | `description` | string | No | `""` | Human-readable label surfaced to agents and the Aperture UI. | | `context` | string or JSON | No | N/A | Prompt or context information to help models understand the connector. Accepts a plain string or arbitrary JSON object. Visible to all authenticated users through MCP tool discovery. | | `auth` | object | No | N/A | Authentication configuration. Dispatched by the `type` field. | #### Connector ID rules Connector IDs must match the pattern `[a-zA-Z][a-zA-Z0-9]*` (letters and digits only, starting with a letter). Connector IDs cannot contain underscores or hyphens because the MCP wire format reserves these as separators: underscores separate the connector ID from the tool name (`snowflake_query`), and hyphens separate the connector ID from resource URIs (`snowflake-resource://...`). Valid IDs: `github`, `snowflake`, `analyticsV2`. Invalid IDs: `my-mcp` (hyphen), `github_api` (underscore), `2fast` (starts with digit). The IDs `tailscale`, `internal`, and `aperture` are reserved and cannot be used as connector IDs. The `aperture` ID is used by the built-in system connector. The restriction on hyphens may be relaxed in a future release. Treat the letters-and-digits rule as current behavior, not a permanent guarantee. Refer to the [connectors reference][kb-aperture-connectors-reference] for the full ID rules. #### Auth types The `auth` object's `type` field selects the authentication scheme. The following table describes the available auth types: | Type | Required fields | Description | | --------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bearer_token` | `secret` | Static `Authorization: Bearer ` header. | | `api_key` | `secret`, `name`, `in` | Credential injected as a named header or query parameter. `in` must be `"header"` or `"query"`. | | `basic` | `username`, `password` | HTTP Basic authentication. | | `oauth2_client_credentials` | `client_id`, `client_secret`, `token_url` | Machine-to-machine OAuth 2.0 token. Auto-refreshed. Optional `scopes` array. | | `oauth2_authorization_code` | `client_id`, `auth_url`, `token_url` | Per-user OAuth 2.0 consent flow. Optional `client_secret` (not required for PKCE-only), `scopes`, and `auth_params`. | | `oauth2_dcr` | `url` | Per-user OAuth 2.0 consent flow using dynamic client registration. Aperture discovers the authorization server and registers a client at runtime, so no `client_id`, `auth_url`, or `token_url` is needed. Optional `scopes` and `auth_params`. | The following example shows a connector with OAuth 2.0 client credentials authentication: ```json { "connectors": { "servers": { "analytics": { "protocol": "mcp", "url": "https://analytics.example.com/v1/mcp", "auth": { "type": "oauth2_client_credentials", "client_id": "aperture-analytics", "client_secret": "secret-example", "token_url": "https://auth.example.com/oauth2/token", "scopes": ["read:data"] } } } } } ``` #### HTTP connectors When `protocol` is `"http"`, Aperture acts as an authenticated reverse proxy. Aperture forwards requests sent to `/v1/connectors//` to the connector's upstream URL and injects credentials automatically. When at least one HTTP connector is configured, Aperture registers an `aperture_list_connectors` MCP tool so that AI models can discover available HTTP connectors. > **Warning:** > > The authentication credentials configured on an HTTP connector are shared by all users with a matching `connectors` grant. Users must have a grant matching `"connectorID/proxy"` or a broader pattern like `"connectorID/**"` to access the proxy endpoint. Use the narrowest possible credential scope (ideally read-only) and do not put sensitive information in the `description` or `context` fields, which are visible to all users. #### Migration from `mcp.servers` The `connectors` section replaces the deprecated `mcp.servers` syntax. At load time, Aperture automatically folds legacy `mcp.servers` entries into `connectors.servers` with `protocol: "mcp"` and no authentication. Both sections can coexist during migration, but connector IDs must be unique across both. Aperture rejects duplicate IDs at load time. Consider the following `mcp.servers` entry: ```json "mcp": { "servers": { "docs": { "url": "http://mcp-server.example.ts.net:8185/v1/mcp" } } } ``` The equivalent `connectors` entry is: ```json "connectors": { "servers": { "docs": { "protocol": "mcp", "url": "http://mcp-server.example.ts.net:8185/v1/mcp" } } } ``` For the full connectors schema and per-category grant reference, refer to the [connectors reference][kb-aperture-connectors-reference]. ### `mcp` > **Note:** > > The `mcp.servers` syntax is deprecated. Use the [`connectors`][ar-connectors-section] section instead, which supports the same functionality plus authenticated connections and the `http` protocol. Aperture retains the `mcp` section for backward compatibility and for the `accept_registrations` field, which has no `connectors` equivalent. The `mcp` section configures MCP (Model Context Protocol) server proxying. Aperture connects to remote MCP servers, aggregates their tools, resources, and resource templates, and exposes them through a single `/v1/mcp` endpoint. Refer to [MCP server proxying][kb-aperture-set-up-mcp-servers] for setup instructions and troubleshooting. ```json { "mcp": { "accept_registrations": true, "servers": { "docs": { "url": "http://mcp-server.example.ts.net:8185/v1/mcp" } } } } ``` #### `mcp` fields | Field | Type | Default | Description | | ---------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accept_registrations` | boolean | `false` | Allow backends to register dynamically through `POST /v1/mcp/register`. Backends POST `{"url": "http://..."}` and keep the connection open. Tools are unregistered when the connection closes. This field has no `connectors` equivalent. | | `servers` | map | `{}` | Map of server ID to server configuration. Deprecated: use `connectors.servers` instead. The map key is the server ID, which becomes the name prefix for tools (`serverID_toolname`), resources (`serverID-uri`), and resource templates (`serverID-uriTemplate`) from that backend. | #### `servers` fields Each entry in the `servers` map accepts the following fields: | Field | Type | Required | Description | | ----- | ------ | -------- | ------------------------------------------------------------------------------------------ | | `url` | string | Yes | The MCP server endpoint URL (for example, `http://mcp-server.example.ts.net:8185/v1/mcp`). | ### `database` The `database` section configures data storage behavior, including raw body persistence, encrypted blob handling, and retention policies for captured request and response data. ```json { "database": { "save_raws": false, "keep_encrypted_blobs": false, "retention": { "duration": "30d", "require_export": false, "purge": ["captures"] } } } ``` #### `database` fields | Field | Type | Default | Description | | ---------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `save_raws` | boolean | `false` | Store the raw HTTP request and response bytes alongside the parsed JSON capture. When `false` and JSON parsing succeeds, raw bodies are discarded to save disk space. Raw bodies are always saved when JSON parsing fails, regardless of this setting, to support debugging. | | `keep_encrypted_blobs` | boolean | `false` | Preserve encrypted content blocks (signatures, encrypted content, encrypted indexes) in stored request and response bodies. By default, these large blobs are replaced with `(redacted)` to reduce storage and processing overhead. Enable when you need to replay requests or inspect encrypted content. | | `retention` | object | `{}` | Capture data retention policy. Refer to the following retention fields. | #### `database.retention` fields | Field | Type | Default | Description | | :--------------- | :------ | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `duration` | string | `""` | How long to keep capture data before purging. Examples: `"30d"`, `"720h"`. An empty string keeps data forever. Set to `"0"` for zero data retention; when `require_export` is `false`, bodies are never written to disk; when `require_export` is `true`, bodies are written, exported to S3, then purged locally. For non-zero values, the minimum is 1 hour and the maximum is 3650 days. | | `require_export` | boolean | `false` | When `true`, Aperture purges only captures that have been successfully exported to an Amazon S3-compatible endpoint. Captures that have not been exported are retained regardless of `duration`. | | `purge` | array | `["captures"]` | What to delete when purging. `["captures"]` deletes request and response bodies and headers but preserves tool use data. `["captures", "tools"]` also deletes tool use data. Metrics (token counts, model, cost, duration, status code) are always preserved regardless of this setting. | When Aperture purges a capture, it removes the request body, response body, and headers. Aperture always preserves the metric record (token counts, model, cost estimate, duration, and status code). This means the dashboard continues to show usage analytics and cost data for purged records. Aperture removes only the full request and response detail. > **Note:** > > For step-by-step guidance on configuring zero data retention, where Aperture never writes request or response bodies to disk, refer to [Configure zero-retention mode][kb-aperture-zero-retention]. For an overview of Aperture's retention and privacy controls, refer to [Privacy and data retention][kb-aperture-privacy]. ### `chat_models` The `chat_models` section curates which models appear in the Aperture chat UI picker, with display names, ordering priority, and utility model roles (title generation and summarization). This section does not grant access. Access still flows through `grants`. When `chat_models` is populated, only models matching both a grant and a `chat_models` entry appear in the chat picker. When omitted or empty, the chat picker shows all granted models whose provider declares a chat-compatible API, with their raw model ID as the label. > **Note:** > > The chat UI is available by default. Set `enable_chat_ui` to `false` in a [grant][ar-grant-capability-fields] to disable it. The `chat_models` section controls what the chat UI shows, not who can access it. ```json { "chat_models": [ {"model": "anthropic/claude-opus-4-8", "display_name": "Opus 4.8", "priority": 100}, {"model": "anthropic/claude-sonnet-4-6", "display_name": "Sonnet 4.6", "priority": 90}, {"model": "anthropic/claude-haiku-4-5", "display_name": "Haiku 4.5", "priority": 70, "title_gen": true, "summarize": true}, {"model": "openai/gpt-5*", "priority": 50} ] } ``` #### `chat_models` fields Each entry in the `chat_models` array accepts the following fields: | Field | Type | Default | Description | | -------------- | ------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | string | (required) | Fully qualified `provider/model` glob pattern using the same syntax as `grants.models` (`*` matches any characters within a single path segment, `**` matches zero or more segments). | | `display_name` | string | `""` | Label shown in the chat picker. When empty, falls back to the model's short ID (the part after the provider prefix). | | `priority` | integer | `0` | Picker ordering priority. Higher values appear first. Ties are broken alphabetically by model ID. Also used as the tiebreaker for utility model selection. | | `title_gen` | boolean | `false` | Flags this entry as eligible for conversation-title generation. The chat service selects the highest-priority `title_gen` entry whose model the user is granted. Falls back to the conversation's chosen model when nothing qualifies. | | `summarize` | boolean | `false` | Flags this entry as eligible for summarizing extended reasoning blocks in chat responses. Selection follows the same rules as `title_gen`. The `title_gen` and `summarize` roles are independent. | | `hidden` | boolean | `false` | Excludes matching models from the chat picker while keeping them eligible for the `title_gen` and `summarize` roles. Use it to reserve a model for background tasks without offering it for responses. | When multiple entries match the same model, the most specific glob wins (for example, `"anthropic/claude-opus-4-7"` beats `"anthropic/**"` which beats `"**"`). Ties on specificity fall back to configuration order (earlier wins). > **Note:** > > The chat picker only includes models whose provider declares a chat-compatible API: `anthropic_messages`, `openai_chat`, `openai_responses`, `gemini_generate_content`, or `google_generate_content` (for Gemini models). Models served only through other formats, such as Amazon Bedrock, do not appear regardless of `chat_models` entries. ### `flags` The `flags` section enables experimental features that are not yet generally available. Each flag is identified by a string key and contains a `value` boolean. All flags default to disabled (`false`). Adding a flag to the configuration enables it. ```json { "flags": { "connectors": { "chat_sandbox": { "value": true } } } ``` Each key is a flag ID. The value object must contain a `value` field set to `true` to enable the flag. Setting `value` to `false` or omitting the flag entirely leaves the feature disabled. #### Flag reference | Flag ID | Name | What it controls | Status | | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `connectors` | Connectors | Enables the `connectors` configuration section, the Connectors tab in the Aperture UI, and the `/v1/connectors/` REST API endpoints. Without this flag, the `connectors` section is silently ignored. | Experimental (hidden) | | `web_tools` | Web Tools | Enables the `aperture_web_search` and `aperture_web_fetch` MCP tools, powered by EXA. Requires the `LLM_PROXY_EXA_API_KEY` environment variable or `-exa-api-key` flag. | Experimental (hidden) | > **Note:** > > Experimental flags are hidden by default in the Aperture UI. To enable a hidden flag, edit the configuration JSON directly (Settings page, JSON editor) or use the Shift+F keyboard shortcut in the Aperture dashboard to access hidden flags by ID. Hidden flags become visible in the UI once enabled. #### Validation behavior Unknown flag IDs produce a validation warning: `unknown flag "{key}" in flags config`. This warning blocks saves through the API or dashboard (where warnings are treated as errors) but lets Aperture start from file. #### Connectors flag The `connectors` flag has the following effects: * **Config section acceptance:** When enabled, Aperture processes the [`connectors`][ar-connectors-section] section at load time. When disabled, the section is silently ignored. * **UI tab:** The Connectors tab appears in the Aperture dashboard for admin users. * **REST API endpoints:** The `/v1/connectors/` endpoints become active for HTTP connector proxying. For the full connectors configuration schema, refer to the [`connectors`][ar-connectors-section] section on this page and the [connectors feature guide][kb-aperture-connectors]. ## Quota enforcement Aperture enforces quotas at request time by checking all referenced buckets before forwarding a request to the provider. ### What happens when a request exceeds a quota When a request would exceed any of its quota buckets, Aperture: 1. Rejects the request with HTTP status **429 (Too Many Requests)**. 2. Sets a `Retry-After` header with the estimated seconds until enough budget refills. 3. Formats the error to match the provider's native error format. 4. Logs a warning with the bucket detail, login name, and model. The following table describes the provider-specific error formats: | Provider | Error format | | :------------ | :------------------------------------------------------------------------------------ | | Anthropic | `{"type":"error","error":{"type":"rate_limit_error","message":"..."}}` | | OpenAI | `{"error":{"message":"...","type":"insufficient_quota","code":"insufficient_quota"}}` | | Bedrock | `{"message":"..."}` with `x-amzn-ErrorType: ThrottlingException` | | Google/Vertex | `{"error":{"code":429,"message":"...","status":"RESOURCE_EXHAUSTED"}}` | ### How clients observe enforcement When Aperture blocks a request for exceeding a quota, the client receives an HTTP 429 response. The blocked request also appears on the dashboard **Logs** page with a 429 status. ## Validation Aperture validates configuration at load time and reports problems. Some issues are fatal errors that prevent the configuration from loading, while others are warnings that let the configuration load but that you should address. The following table describes the validations. > **Note:** > > Aperture handles validation differently depending on how the configuration is loaded: > > * **When Aperture loads configuration at startup or reload**: Aperture loads the configuration successfully even if it has warnings. This lets Aperture start even with minor issues. > * **When saving through the API or the dashboard's Administration pages**: Aperture treats warnings as errors and rejects the save. This ensures that configurations saved through the UI are warning-free. > * **When using the validate endpoint (`POST /aperture/config:validate`)**: Aperture surfaces warnings as validation errors (the response sets `Valid: false`), matching the save behavior. > > The admin lockout check only applies when saving. It prevents you from accidentally removing your own admin access. | Condition | Message | Severity | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | No providers or MCP servers | `no providers or mcp servers defined; users will not be able to access any models` | Warning | | Provider missing `baseurl` | `provider {id} has no baseurl configured` | Warning | | Invalid `authorization` type | `provider {id} has invalid authorization type: {type}` | Warning | | Unresolved environment variable | `unsubstituted macros: [var_name]` | Error | | Invalid JSON or HUJSON syntax | Parse error details | Error | | Invalid quota definition | `quota {name}: {details}` | Error | | **Structural / syntax** | | | | Duplicate keys in configuration | `duplicate config key "hostname"` | Warning | | Unknown configuration keys | `unknown config key "basurl"` | Warning | | Type mismatch in field value | Field name and `json.UnmarshalTypeError` details | Warning | | **Provider** | | | | Invalid `add_headers` format | `provider {id}: add_headers entry "Bad-Entry" must be in "Header-Name: value" format` | Warning | | **Quota** | | | | Invalid quota name template | `quota "{name}": quota name "{name}" has unsupported template "{template}" after colon` | Warning | | **Grant** | | | | Unknown fields in grant | Strict JSON parsing error for the unrecognized field | Warning | | Grant `models` references undefined provider | `models pattern "{pattern}" references provider "{name}" which does not match any declared provider` | Warning | | Grant `mcp_tools`, `mcp_resources`, or `mcp_templates` references undefined MCP server | `mcp_tools pattern "{pattern}" references server "{name}" which does not match any declared MCP server` | Warning | | Grant `send_hooks` references undefined hook | `send_hooks references undefined hook "{name}"` | Warning | | Grant `quotas` references undefined quota | `quotas references undefined quota "{name}"` | Warning | | Invalid quota bucket ref template in grant | `grants[{n}] grant {n} quotas[{n}]: bucket ref "{ref}" has unsupported template...` | Warning | | Grant-level `add_headers` invalid format | `add_headers entry "{entry}" must be in "Header-Name: value" format` | Warning | | **Connector** | | | | Connector missing `protocol` | `connectors.servers.{id}: protocol is required (e.g. "mcp" or "http")` | Error | | Unsupported connector protocol | `connectors.servers.{id}: unsupported protocol "{value}" (supported: "mcp", "http")` | Error | | Invalid connector ID | `connectors.servers.{id}: invalid ID "{id}"; connector IDs must match [a-zA-Z][a-zA-Z0-9]* (letters and digits only, starting with a letter; no hyphens or underscores)` | Error | | Connector missing URL | `connectors.servers.{id}: URL is required` | Warning | | Connector auth validation failure | `connectors.servers.{id}.auth: {details}` | Error | | Duplicate connector ID across `mcp` and `connectors` | `config: server ID "{id}" is defined in both 'mcp.servers' and 'connectors.servers'; IDs must be unique across both sections` | Error | | **Hook** | | | | Hook missing URL | `hook {name} has no url configured` | Warning | | Hook invalid URL scheme | `hook {name} has invalid URL scheme (must be http:// or https://): {url}` | Warning | | Hook invalid authorization type | `hook {name} has invalid authorization type: {type}` | Warning | | **Exporter** | | | | S3 prefix ends with `/` | `exporters.s3.prefix must not end with a slash` | Warning | | **Structural warnings** | | | | No grants assign admin role | `no grant in grants or temp_grants assigns role:admin; nobody will be able to manage this instance` | Warning | | Providers configured but no grants defined | `providers are configured but no grants or temp_grants defined; all access will be denied` | Warning | | **Save-only** | | | | Empty configuration | `config must not be empty` | Error | | Admin lockout prevention | Rejects saves that would remove the saving user's admin access | Error | | **Exporter silent cap** | | | | S3 exporter `limit` exceeds 10000 | Aperture silently reduces `limit` to `10000` | Silent | For common validation issues and how to resolve them, refer to [troubleshooting][kb-aperture-troubleshooting]. ## Complete example The following example shows a complete configuration with all sections: ```json { // Access control: who can use which models "grants": [ // All users: access all models with per-user and org-wide quotas { "src": ["*"], "app": { "tailscale.com/cap/aperture": [ { "role": "user" }, { "models": "**", "quotas": [ {"bucket": "daily:"}, {"bucket": "org-monthly"}, ], }, ], }, }, // Admin access for specific user with audit hook { "src": ["admin@company.com"], "app": { "tailscale.com/cap/aperture": [ { "role": "admin" }, { "models": "**", "send_hooks": [ { "name": "oso", "events": ["tool_call_entire_request"], "send": ["tools", "estimated_cost"], }, ], }, ], }, }, // CORS headers for browser-based clients { "src": ["browser-app@example.com"], "app": { "tailscale.com/cap/aperture": [ { "set_cors": true, "cors_paths": ["/v1/**", "/bedrock/**"], "Access-Control-Allow-Origin": "https://app.example.com", "Access-Control-Allow-Methods": "POST, OPTIONS", "Access-Control-Allow-Headers": "Content-Type, Authorization", }, ], }, }, ], // Dollar-based spending limits "quotas": { "daily:": { "capacity": "$10.00", "rate": "$5.00/day", "on_exceed": "reject", }, "org-monthly": { "capacity": "$2000.00", "rate": "$2000.00/month", "on_exceed": "reject", }, }, // LLM session log export configuration "exporters": { "s3": { // Required for S3-compatible services such as GCS "endpoint": "https://your-s3-compatible-endpoint.url", "bucket_name": "aperture-exports", "region": "us-west-2", "prefix": "prod", "access_key_id": "", "access_secret": "", "every": 3600, "limit": 1000 } }, // LLM providers "providers": { "openai": { "baseurl": "https://api.openai.com", "apikey": "", "models": ["gpt-5.5", "gpt-5.4-mini", "gpt-5.4"], "name": "OpenAI", "description": "OpenAI models for coding and chat", "compatibility": { "openai_chat": true, "openai_responses": true } }, "anthropic": { "baseurl": "https://api.anthropic.com", "apikey": "", "authorization": "x-api-key", "models": ["claude-sonnet-4-6", "claude-haiku-4-5", "claude-opus-4-8"], "name": "Anthropic", "compatibility": { "openai_chat": false, "anthropic_messages": true } }, "gemini": { "baseurl": "https://generativelanguage.googleapis.com", "apikey": "", "authorization": "x-goog-api-key", "models": ["gemini-2.5-flash", "gemini-2.5-pro"], "name": "Google Gemini", "compatibility": { "openai_chat": false, "gemini_generate_content": true } }, "private": { "baseurl": "", "models": ["qwen3-coder-30b"] } }, // Hooks for external integrations "hooks": { "oso": { "url": "https://api.osohq.com/api/agents/v1/model-request", "apikey": "", }, }, // Outbound integrations (MCP servers and HTTP APIs) "connectors": { "servers": { // Unauthenticated MCP server on your tailnet "tailnetMCP": { "protocol": "mcp", "url": "http://mcp-server.example.ts.net:8080/v1/mcp", }, // MCP server with bearer token auth "snowflake": { "protocol": "mcp", "url": "https://mcp.example.com/v1/mcp", "auth": { "type": "bearer_token", "secret": "sk-example-token", }, }, }, }, // Dynamic MCP registration (accept_registrations has no connectors equivalent) "mcp": { "accept_registrations": true, }, // Data storage settings "database": { "save_raws": false, "keep_encrypted_blobs": false, "retention": { "duration": "30d", "require_export": false, "purge": ["captures"], }, }, // Data storage settings "database": { "save_raws": false, "keep_encrypted_blobs": false, "retention": { "duration": "30d", "require_export": false, "purge": ["captures"], }, }, } ``` ## Related The following topics provide additional information about configuring and managing Aperture: * For supported providers, compatibility flags, and cost basis values, refer to the [provider compatibility reference][kb-aperture-provider-compatibility]. * For step-by-step provider setup, refer to the [set up LLM providers][kb-aperture-set-up-providers] guides. * For instructions on controlling model access, refer to [grant access to models][kb-aperture-grant-model-access]. * For common configuration issues, refer to [troubleshooting][kb-aperture-troubleshooting]. * For the Aperture admin dashboard, refer to the [admin dashboard reference][kb-aperture-dashboard-admin]. [ar-auth-mode]: #auth_mode [ar-connectors-section]: #connectors [ar-flags-section]: #flags [ar-grant-capability-fields]: #additional-capability-fields [ar-hook-send-types]: #hook-send-types [ar-hooks]: #hooks [co-pricing]: /pricing [kb-aperture-build-custom-webhook]: /docs/aperture/how-to/build-custom-webhook [kb-aperture-connectors-reference]: /docs/aperture/connectors/reference [kb-aperture-connectors]: /docs/aperture/connectors [kb-aperture-dashboard-admin]: /docs/aperture/reference/dashboard-admin [kb-aperture-export-s3]: /docs/aperture/how-to/export-usage-data-to-s3 [kb-aperture-grant-mcp-tool-access]: /docs/aperture/how-to/grant-mcp-tool-access [kb-aperture-grant-model-access]: /docs/aperture/how-to/grant-model-access [kb-aperture-integrate-cerbos]: /docs/aperture/integrate/cerbos [kb-aperture-integrate-oso]: /docs/aperture/integrate/oso [kb-aperture-monitor-quota-balances]: /docs/aperture/how-to/check-and-refill-budgets [kb-aperture-privacy]: /docs/aperture/privacy-and-data-retention [kb-aperture-provider-compatibility-model-cost-map]: /docs/aperture/provider-compatibility#model-cost-map [kb-aperture-provider-compatibility]: /docs/aperture/provider-compatibility [kb-aperture-reference]: /docs/aperture/reference [kb-aperture-set-per-user-spending-limits]: /docs/aperture/how-to/set-per-user-spending-limits [kb-aperture-set-team-budget]: /docs/aperture/how-to/set-team-budget [kb-aperture-set-up-admin-access]: /docs/aperture/how-to/set-up-admin-access [kb-aperture-set-up-mcp-servers]: /docs/aperture/mcp-server [kb-aperture-set-up-providers]: /docs/aperture/set-up-providers [kb-aperture-troubleshoot-405]: /docs/aperture/troubleshooting#http-405-error-from-upstream-provider [kb-aperture-troubleshooting]: /docs/aperture/troubleshooting [kb-aperture-visible-groups]: /docs/aperture/visible-groups [kb-aperture-zero-retention]: /docs/aperture/how-to/configure-zero-retention [kb-aperture]: /docs/aperture [kb-tailscale-grants]: /docs/features/access-control/grants/grants-app-capabilities [kb-use-passthrough-mode]: /docs/aperture/how-to/use-passthrough-mode [xt-anthropic-models]: https://platform.claude.com/docs/en/about-claude/models/overview [xt-anthropic-plans]: https://www.anthropic.com/pricing [xt-aperture-signup]: https://aperture.tailscale.com [xt-gemini-plans]: https://gemini.google.com [xt-openai-models]: https://platform.openai.com/docs/models [xt-openai-plans]: https://openai.com/chatgpt/pricing