See everything you missed at TailscaleUp.Read the recap →

Manage an existing Oso integration

Last validated:

Oso is an authorization platform that provides fine-grained access control for AI agents. This topic is for Aperture admins managing an existing Oso integration.

Aperture sends tool use data to Oso using the hooks system. The hook defines the Oso endpoint, and a grant specifies which requests trigger the hook and what data to include.

Oso is a third-party service. When Aperture forwards request data to it, Oso's use of that data is governed by your agreement with Oso, not your agreement with Tailscale.

Oso uses asynchronous hooks (tool_call_entire_request) that fire after the response completes. For synchronous pre-request enforcement that can block or modify requests before they reach the provider, refer to guardrails.

Prerequisites

Before you begin, ensure you have the following:

  • Access to your Aperture gateway.
  • The admin role in Aperture to access the admin dashboard and edit configuration.
  • An existing Oso integration configured in Aperture and access to its Oso account.

Review or update the Oso hook

To review or update an existing integration:

  1. Open the Aperture admin dashboard and go to Administration > Configuration.

  2. Find the existing oso entry in the hooks section. If you need to replace its API key, update the apikey value with a key from your Oso account.

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

    Keep the existing endpoint unless Oso instructs you to change it.

  3. Review the grants with a send_hooks entry that references the oso hook. Each grant controls which requests trigger the hook and what data Aperture sends. For example:

    "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 forwards full request and response bodies (request_body and response_body), which contain prompt and model-output content, not just tool-use metadata. Send only the data Oso needs for your authorization policies. To limit which users' requests trigger the hook, replace "*" in the src field with specific user identities or tags.

  4. Save the configuration.

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

The grant examples on this page use Aperture configuration syntax, where the dst field is not required because the destination is the Aperture device itself. If you define grants in the tailnet policy file instead, you must include a dst key specifying the Aperture device (for example, "dst": ["tag:aperture"]). Omitting dst in a tailnet policy file grant causes the grant to silently have no effect. For a full comparison and conversion steps, refer to Aperture grants vs. tailnet policy file grants.

Verify the integration

After updating the Oso hook or its grants, verify that Aperture is sending the intended data to Oso.

  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