{"slug":"integrate-oso-with-aperture","title":"Integrate Oso with Aperture","tags":["tailscale"],"agent_summary":"Last validated: Apr 9, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Integrate Oso 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[Oso](https://www.osohq.com/) is an authorization platform that provides fine-grained access control for AI agents. By connecting Aperture to Oso, you can send tool use data from LLM requests so Oso can make authorization decisions and provide observability into what your AI agents are doing.\r\n\r\nAperture sends data to Oso using the [hooks system](https://tailscale.com/docs/aperture/configuration#hooks). You configure a hook endpoint for Oso 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-oso\\#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- An [Oso](https://www.osohq.com/) account with an API key. If you don't have one, you can sign up from the Aperture dashboard.\r\n\r\n## [Configure the Oso hook](https://tailscale.com/docs/aperture/how-to/integrate-oso\\#configure-the-oso-hook)\r\n\r\nTo integrate Oso with Aperture, configure a hook in Aperture that points to the Oso API endpoint. This lets you send tool use data to Oso for authorization decisions and observability.\r\n\r\n1. Open the Aperture dashboard at `http://ai/ui/`.\r\n\r\n2. Go to the **Tool Use** page, then select **View Tool Use in Oso**.\r\n\r\n3. Sign in to your Oso account (or sign up) and create an API key.\r\n\r\n4. Navigate to the **Settings** page and open the JSON editor.\r\n\r\n5. Add an `oso` entry in the `hooks` section with your API key.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```json\r\n\"hooks\": {\r\n \"oso\": {\r\n \"url\": \"https://api.osohq.com/api/agents/v1/model-request\",\r\n \"apikey\": \"YOUR_OSO_API_KEY\"\r\n }\r\n}\r\n```\r\n\r\n\r\n\r\nReplace `YOUR_OSO_API_KEY` with the API key you created in step 3.\r\n\r\n6. Add a grant with a `send_hooks` entry that references the `oso` 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\": \"oso\",\\\r\n \"events\": [\"tool_call_entire_request\"],\\\r\n \"send\": [\"user_message\", \"tools\", \"request_body\", \"response_body\"]\\\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 tool call data for all users. To limit which users' requests trigger the hook, replace `\"*\"` in the `src` field with specific user identities or tags.\r\n\r\n7. 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-oso\\#verify-the-integration)\r\n\r\nAfter configuring the Oso hook, verify that Aperture is sending data to Oso and that it appears in the Oso dashboard.\r\n\r\n1. Send a request through Aperture that includes a tool call and matches your grant conditions.\r\n2. Open the [Oso dashboard](https://www.osohq.com/) and confirm the tool use data appears.\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-oso\\#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":"

Integrate Oso with Aperture

\n

Last validated: Apr 9, 2026

\n

Aperture by Tailscaleis currently in alpha.

\n

Oso is an authorization platform that provides fine-grained access control for AI agents. By connecting Aperture to Oso, you can send tool use data from LLM requests so Oso can make authorization decisions and provide observability into what your AI agents are doing.

\n

Aperture sends data to Oso using the hooks system. You configure a hook endpoint for Oso and a grant that specifies which requests trigger the hook and what data to include.

\n

Prerequisites

\n

Before you begin, ensure you have the following:

\n\n

Configure the Oso hook

\n

To integrate Oso with Aperture, configure a hook in Aperture that points to the Oso API endpoint. This lets you send tool use data to Oso for authorization decisions and observability.

\n
    \n
  1. \n

    Open the Aperture dashboard at http://ai/ui/.

    \n
    2. \n
  2. \n

    Go to the Tool Use page, then select View Tool Use in Oso.

    \n
    3. \n
  3. \n

    Sign in to your Oso account (or sign up) and create an API key.

    \n
    4. \n
  4. \n

    Navigate to the Settings page and open the JSON editor.

    \n
    5. \n
  5. \n

    Add an oso entry in the hooks section with your API key.

    \n
    6. \n
\n
\"hooks\": {\r\n       \"oso\": {\r\n           \"url\": \"https://api.osohq.com/api/agents/v1/model-request\",\r\n           \"apikey\": \"YOUR_OSO_API_KEY\"\r\n       }\r\n}\n
\n

Replace YOUR_OSO_API_KEY with the API key you created in step 3.

\n
    \n
  1. Add a grant with a send_hooks entry that references the oso hook. The grant controls which requests trigger the hook and what data Aperture sends.
    2. \n
\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\": \"oso\",\\\r\n                               \"events\": [\"tool_call_entire_request\"],\\\r\n                               \"send\": [\"user_message\", \"tools\", \"request_body\", \"response_body\"]\\\r\n                           }\\\r\n                       ]\\\r\n                   }\\\r\n               ]\\\r\n           }\\\r\n       }\\\r\n]\n
\n

This configuration sends tool call data for all users. To limit which users' requests trigger the hook, replace \"*\" in the src field with specific user identities or tags.

\n
    \n
  1. Save the configuration.
    2. \n
\n

For details on hook events and send types, refer to the hooks configuration reference.

\n

Verify the integration

\n

After configuring the Oso hook, verify that Aperture is sending data to Oso and that it appears in the Oso dashboard.

\n
    \n
  1. Send a request through Aperture that includes a tool call and matches your grant conditions.
    2. \n
  2. Open the Oso dashboard and confirm the tool use data appears.
    3. \n
\n

If 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.

\n

Next steps

\n\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}