{"slug":"integrate-cerbos-with-aperture","title":"Integrate Cerbos with Aperture","tags":["tailscale"],"agent_summary":"Last validated: Apr 9, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Integrate Cerbos with Aperture\r\n\r\nLast validated: Apr 9, 2026\r\n\r\nAperture by Tailscaleis currently [in alpha](https://tailscale.com/docs/reference/tailscale-release-stages#alpha).\r\n\r\n[Cerbos](https://www.cerbos.dev/) is a policy engine that provides fine-grained, context-aware authorization. By connecting Aperture to Cerbos, you can send LLM request data to Cerbos so it can enforce authorization policies on AI usage, such as controlling which users can access specific models or tools.\r\n\r\nAperture sends data to Cerbos using the [hooks system](https://tailscale.com/docs/aperture/configuration#hooks). You configure a hook endpoint for your Cerbos deployment and a grant that specifies which requests trigger the hook and what data to include.\r\n\r\n## [Prerequisites](https://tailscale.com/docs/aperture/how-to/integrate-cerbos\\#prerequisites)\r\n\r\nBefore you begin, ensure you have the following:\r\n\r\n- A running [Aperture instance](https://tailscale.com/docs/aperture/get-started) accessible from your device.\r\n- A [Cerbos](https://www.cerbos.dev/) deployment (self-hosted or Cerbos Hub) with an API endpoint that can receive webhook data.\r\n\r\n## [Configure the Cerbos endpoint](https://tailscale.com/docs/aperture/how-to/integrate-cerbos\\#configure-the-cerbos-endpoint)\r\n\r\nTo integrate Cerbos with Aperture, configure the Cerbos endpoint so you can use it as a hook in Aperture and set up a grant to send request data to that hook. This allows Cerbos to receive real-time data about LLM requests for authorization decisions.\r\n\r\n1. In your Cerbos deployment, identify or create an endpoint that can receive HTTP POST requests from Aperture.\r\n2. Note the endpoint URL and any API key or authentication token. You'll use these when configuring the hook in Aperture.\r\n\r\nFor details on setting up Cerbos, refer to the [Cerbos documentation](https://docs.cerbos.dev/).\r\n\r\n## [Configure the Aperture hook](https://tailscale.com/docs/aperture/how-to/integrate-cerbos\\#configure-the-aperture-hook)\r\n\r\nConfigure a hook in Aperture that points to your Cerbos endpoint. This lets you send request data to Cerbos for authorization decisions.\r\n\r\n1. Open the Aperture dashboard at `http://ai/ui/`.\r\n\r\n2. Navigate to the **Settings** page and open the JSON editor.\r\n\r\n3. Add a `cerbos` entry in the `hooks` section with the endpoint URL from your Cerbos deployment.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```json\r\n\"hooks\": {\r\n       \"cerbos\": {\r\n           \"url\": \"YOUR_CERBOS_ENDPOINT_URL\",\r\n           \"apikey\": \"YOUR_CERBOS_API_KEY\"\r\n       }\r\n}\r\n```\r\n\r\n\r\n\r\nReplace `YOUR_CERBOS_ENDPOINT_URL` with the URL of your Cerbos endpoint and `YOUR_CERBOS_API_KEY` with the API key from your Cerbos deployment.\r\n\r\n4. Add a grant with a `send_hooks` entry that references the `cerbos` hook. The grant controls which requests trigger the hook and what data Aperture sends.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```json\r\n\"grants\": [\\\r\n       {\\\r\n           \"src\": [\"*\"],\\\r\n           \"app\": {\\\r\n               \"tailscale.com/cap/aperture\": [\\\r\n                   {\\\r\n                       \"send_hooks\": [\\\r\n                           {\\\r\n                               \"name\": \"cerbos\",\\\r\n                               \"events\": [\"entire_request\"],\\\r\n                               \"send\": [\"tools\", \"user_message\", \"grants\"]\\\r\n                           }\\\r\n                       ]\\\r\n                   }\\\r\n               ]\\\r\n           }\\\r\n       }\\\r\n]\r\n```\r\n\r\n\r\n\r\nThis configuration sends request data for all users. The `grants` send type includes the user's custom capabilities, which Cerbos can use for authorization decisions. To limit which users' requests trigger the hook, replace `\"*\"` in the `src` field with specific user identities or tags.\r\n\r\n5. Save the configuration.\r\n\r\n\r\nFor details on hook events and send types, refer to the [hooks configuration reference](https://tailscale.com/docs/aperture/configuration#hooks).\r\n\r\n## [Verify the integration](https://tailscale.com/docs/aperture/how-to/integrate-cerbos\\#verify-the-integration)\r\n\r\nAfter configuring the Cerbos hook, verify that Aperture is sending data to Cerbos and that Cerbos is evaluating it against your policies.\r\n\r\n1. Send a request through Aperture that matches your grant conditions.\r\n2. Check your Cerbos deployment to confirm the request data arrives.\r\n3. Verify that Cerbos evaluates the data against your authorization policies.\r\n\r\nIf data doesn't appear, check that the `send_hooks` name matches the key in your `hooks` section and that the grant's `src` field includes the user who made the request.\r\n\r\n## [Next steps](https://tailscale.com/docs/aperture/how-to/integrate-cerbos\\#next-steps)\r\n\r\n- [Build a custom webhook](https://tailscale.com/docs/aperture/how-to/build-custom-webhook) to send Aperture data to other services.\r\n- Learn about hook events and data types in the [configuration reference](https://tailscale.com/docs/aperture/configuration#hooks).\r\n- Explore other [external integrations](https://tailscale.com/docs/aperture/integrate) for Aperture.\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"<h1>Integrate Cerbos with Aperture</h1>\n<p>Last validated: Apr 9, 2026</p>\n<p>Aperture by Tailscaleis currently <a href=\"https://tailscale.com/docs/reference/tailscale-release-stages#alpha\">in alpha</a>.</p>\n<p><a href=\"https://www.cerbos.dev/\">Cerbos</a> is a policy engine that provides fine-grained, context-aware authorization. By connecting Aperture to Cerbos, you can send LLM request data to Cerbos so it can enforce authorization policies on AI usage, such as controlling which users can access specific models or tools.</p>\n<p>Aperture sends data to Cerbos using the <a href=\"https://tailscale.com/docs/aperture/configuration#hooks\">hooks system</a>. You configure a hook endpoint for your Cerbos deployment and a grant that specifies which requests trigger the hook and what data to include.</p>\n<h2><a href=\"https://tailscale.com/docs/aperture/how-to/integrate-cerbos#prerequisites\">Prerequisites</a></h2>\n<p>Before you begin, ensure you have the following:</p>\n<ul>\n<li>A running <a href=\"https://tailscale.com/docs/aperture/get-started\">Aperture instance</a> accessible from your device.</li>\n<li>A <a href=\"https://www.cerbos.dev/\">Cerbos</a> deployment (self-hosted or Cerbos Hub) with an API endpoint that can receive webhook data.</li>\n</ul>\n<h2><a href=\"https://tailscale.com/docs/aperture/how-to/integrate-cerbos#configure-the-cerbos-endpoint\">Configure the Cerbos endpoint</a></h2>\n<p>To integrate Cerbos with Aperture, configure the Cerbos endpoint so you can use it as a hook in Aperture and set up a grant to send request data to that hook. This allows Cerbos to receive real-time data about LLM requests for authorization decisions.</p>\n<ol>\n<li>In your Cerbos deployment, identify or create an endpoint that can receive HTTP POST requests from Aperture.</li>\n<li>Note the endpoint URL and any API key or authentication token. You'll use these when configuring the hook in Aperture.</li>\n</ol>\n<p>For details on setting up Cerbos, refer to the <a href=\"https://docs.cerbos.dev/\">Cerbos documentation</a>.</p>\n<h2><a href=\"https://tailscale.com/docs/aperture/how-to/integrate-cerbos#configure-the-aperture-hook\">Configure the Aperture hook</a></h2>\n<p>Configure a hook in Aperture that points to your Cerbos endpoint. This lets you send request data to Cerbos for authorization decisions.</p>\n<ol>\n<li>\n<p>Open the Aperture dashboard at <code>http://ai/ui/</code>.</p>\n</li>\n<li>\n<p>Navigate to the <strong>Settings</strong> page and open the JSON editor.</p>\n</li>\n<li>\n<p>Add a <code>cerbos</code> entry in the <code>hooks</code> section with the endpoint URL from your Cerbos deployment.</p>\n</li>\n</ol>\n<pre><code class=\"language-json\">\"hooks\": {\r\n       \"cerbos\": {\r\n           \"url\": \"YOUR_CERBOS_ENDPOINT_URL\",\r\n           \"apikey\": \"YOUR_CERBOS_API_KEY\"\r\n       }\r\n}\n</code></pre>\n<p>Replace <code>YOUR_CERBOS_ENDPOINT_URL</code> with the URL of your Cerbos endpoint and <code>YOUR_CERBOS_API_KEY</code> with the API key from your Cerbos deployment.</p>\n<ol start=\"4\">\n<li>Add a grant with a <code>send_hooks</code> entry that references the <code>cerbos</code> hook. The grant controls which requests trigger the hook and what data Aperture sends.</li>\n</ol>\n<pre><code class=\"language-json\">\"grants\": [\\\r\n       {\\\r\n           \"src\": [\"*\"],\\\r\n           \"app\": {\\\r\n               \"tailscale.com/cap/aperture\": [\\\r\n                   {\\\r\n                       \"send_hooks\": [\\\r\n                           {\\\r\n                               \"name\": \"cerbos\",\\\r\n                               \"events\": [\"entire_request\"],\\\r\n                               \"send\": [\"tools\", \"user_message\", \"grants\"]\\\r\n                           }\\\r\n                       ]\\\r\n                   }\\\r\n               ]\\\r\n           }\\\r\n       }\\\r\n]\n</code></pre>\n<p>This configuration sends request data for all users. The <code>grants</code> send type includes the user's custom capabilities, which Cerbos can use for authorization decisions. To limit which users' requests trigger the hook, replace <code>\"*\"</code> in the <code>src</code> field with specific user identities or tags.</p>\n<ol start=\"5\">\n<li>Save the configuration.</li>\n</ol>\n<p>For details on hook events and send types, refer to the <a href=\"https://tailscale.com/docs/aperture/configuration#hooks\">hooks configuration reference</a>.</p>\n<h2><a href=\"https://tailscale.com/docs/aperture/how-to/integrate-cerbos#verify-the-integration\">Verify the integration</a></h2>\n<p>After configuring the Cerbos hook, verify that Aperture is sending data to Cerbos and that Cerbos is evaluating it against your policies.</p>\n<ol>\n<li>Send a request through Aperture that matches your grant conditions.</li>\n<li>Check your Cerbos deployment to confirm the request data arrives.</li>\n<li>Verify that Cerbos evaluates the data against your authorization policies.</li>\n</ol>\n<p>If data doesn't appear, check that the <code>send_hooks</code> name matches the key in your <code>hooks</code> section and that the grant's <code>src</code> field includes the user who made the request.</p>\n<h2><a href=\"https://tailscale.com/docs/aperture/how-to/integrate-cerbos#next-steps\">Next steps</a></h2>\n<ul>\n<li><a href=\"https://tailscale.com/docs/aperture/how-to/build-custom-webhook\">Build a custom webhook</a> to send Aperture data to other services.</li>\n<li>Learn about hook events and data types in the <a href=\"https://tailscale.com/docs/aperture/configuration#hooks\">configuration reference</a>.</li>\n<li>Explore other <a href=\"https://tailscale.com/docs/aperture/integrate\">external integrations</a> for Aperture.</li>\n</ul>\n<p><img src=\"https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed\" alt=\"Project Logo\"></p>\n<p>Ask AI</p>\n<p>reCAPTCHA</p>\n<p>Recaptcha requires verification.</p>\n<p>protected by <strong>reCAPTCHA</strong></p>\n"}