APERTURE IS NOW AVAILABLE - START BUILDING WITH AI SAFELY IN MINUTES, NO WAITLIST.Read more →

Integrate Oso with Aperture

Last validated:

Aperture by Tailscale is currently in alpha.

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.

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.

Prerequisites

Before you begin, ensure you have the following:

  • A running Aperture instance accessible from your device.
  • An Oso account with an API key. If you don't have one, you can sign up from the Aperture dashboard.

Configure the Oso hook

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.

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

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

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

  4. Navigate to the Settings page and open the JSON editor.

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

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

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

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

    "grants": [
    {
        "src": ["*"],
        "app": {
            "tailscale.com/cap/aperture": [
                {
                    "send_hooks": [
                        {
                            "name": "oso",
                            "events": ["tool_call_entire_request"],
                            "send": ["user_message", "tools", "request_body", "response_body"]
                        }
                    ]
                }
            ]
        }
    }
]

    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.

  7. Save the configuration.

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

Verify the integration

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

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

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.

Next steps