Custom Authorization Integration
Choose JWT scopes, managed roles, or a custom policy provider for your AgentOS access rules.
AgentOS verifies caller identity before asking an authorization provider whether an operation is allowed. Runtime integrations are part of open-source AgentOS; custom RBAC managed through the hosted control plane has Enterprise plan requirements.
The APIs on this page require Agno 3.1.3 or later.
Choose an Integration
| Existing access model | AgentOS integration |
|---|---|
| JWT contains permissions in Agno's scope vocabulary | BYO Token, with the default scope provider. Use scopes_claim on JWTMiddleware for a different permission claim name. |
| JWT identifies a user whose roles should be stored and edited locally | Managed roles, using role definitions and stored subject assignments. |
| Identity provider sends role names | Authorization(roles_claim="roles"), with local definitions of what each role may do. |
| Existing policy service decides access using tenant membership, relationships, or attributes | Implement AuthorizationProvider and pass it as authorization_provider. |
| Keep AgentOS's managed-role API while replacing its policy storage and decision backend | Implement PolicyEngine and pass it as engine. |
Authorization Provider Contract
Import the integration types from agno.os.authz:
from agno.os import AgentOS, Authorization
from agno.os.authz import AuthorizationContext, AuthorizationProviderEach decision receives an AuthorizationContext containing the verified principal_id, the decoded JWT claims, token scopes, resource_type, resource_id, action, and configured admin_scope. Read tenant or group claims from this context and resolve resource ownership from your trusted policy store.
Implement both decision and listing primitives:
| Method | Contract |
|---|---|
check(ctx) | Return whether the caller may perform the action on the resource. For contexts without a resource family or action, defer to the route gate. |
accessible_resource_ids(ctx) | Return the allowed IDs for the resource family and action. Return an empty set to grant none, or {"*"} to grant all. |
authorize_route(ctx, required_scopes) | Override when your policy permits mapped routes without a resource family, such as /registry, /sessions, /memories, or /config. The base implementation denies these routes when they require permissions. |
require and filter_accessible have defaults built on those primitives. Async counterparts such as acheck, aaccessible_resource_ids, and aauthorize_route run the corresponding sync method in a worker thread by default. Override them when your policy service has a native async client.
After implementing your provider, wire the instance into AgentOS. This snippet assumes provider is your AuthorizationProvider implementation and agent is your existing agent:
agent_os = AgentOS(
id="my-agent-os",
agents=[agent],
authorization=Authorization(
verification_keys=["your-issuer-public-key"],
algorithm="RS256",
verify_audience=True,
audience="my-agent-os",
authorization_provider=provider,
),
user_isolation=True,
)A provider override replaces the default JWT scope decision model. It does not create a managed-role store or mount /authz. By default a custom provider does not trust token scopes, so an agent_os:admin string in the JWT does not grant administration or bypass per-user isolation. Model administration in your policy explicitly. Service-account PATs remain governed by their stored scopes.
See the custom-provider cookbook for a complete implementation, including the route gate. The identity-provider cookbook shows custom claims with RS256 and a local JWKS file.
Keep Managed Roles with a Custom Backend
Use Authorization(engine=your_engine) when you want to keep role definitions, assignments, audit support, and the /authz admin API while changing the backend. PolicyEngine defines role authoring, subject assignments, scope and resource checks, and accessible resource IDs, with sync and async methods. The default engine stores this policy in the bound SQL database.
engine and authorization_provider cannot be set together. See the custom-engine cookbook for the implementation contract.
For a relationship-based model, FGAAuthorizationProvider accepts an FGAClient. The optional OpenFGA adapter is available with agno[fga]; other backends can implement the client interface. See the relationship-based authorization cookbook.
Combine Grant Sources
Authorization(authorization_provider=[provider_a, provider_b]) combines providers with OR: any provider may grant access, and listings use the union of their allowed resources. Use this for independent grant sources, such as operator JWT scopes alongside end-user policy.
Place mandatory restrictions, including tenant membership checks, inside every granting provider or in an upstream authorization layer. Adding a restrictive provider to an OR composition does not constrain grants from another provider. Provider failures grant nothing from that source; another healthy provider may still grant access.
Tenant Data Boundaries
Resource authorization and database isolation are separate. A provider can restrict access to tenant-owned agents, teams, and workflows, but it does not filter arbitrary SQL queries, knowledge searches, tool calls, credentials, or files.
See multitenancy and shared resources for the boundary between these controls.