Delegated authorization
Advanced preview: bridge an existing app login into Auggy with short-lived assertions and route/tool requires rules.
Optional app integration
This surface is not part of the default agent path and does not make Auggy a general application backend. Its API may change before 1.0; pin exact versions and validate authorization and operational boundaries.
Boundary
Advanced preview
Use this only when an existing application must authorize optional Auggy routes or protected tools. Keep the application's identity provider and authorization records as the source of truth.
Delegated authorization lets a Supabase, Clerk, Auth0-style, or custom app session call visitor.required routes and protected tools without making Auggy a general auth provider.
- The app verifies the user session and decides what the user may do.
- The app mints a compact, short-lived Auggy assertion.
- Auggy verifies the signature, audience, provider, key ID, TTL, and replay protection.
- Auggy enforces route-local and tool-local requires rules against assertion scopes and grants.
- Roles can travel as context, but roles do not satisfy authorization requirements.
Team/internal users today
Staff and customers use public recognized identity with app-minted scopes and grants. People operating the Auggy instance use creator access. Per-operator console permissions are future work.
Flow
- BrowserHas a normal app login session.
- BrowserAsks the app backend for an Auggy auth assertion.
- App backendVerifies the session with its trusted provider.
- App backendDerives minimal scopes and resource grants.
- App backendSigns a short-lived assertion.
- BrowserCalls Auggy with x-auggy-auth-assertion.
- AuggyResolves public recognized context and enforces route/tool requires before work runs.
Mint assertions
import { createExternalAuthAssertion } from "auggy";
export async function mintAuggyAssertionForUser(user: {
id: string;
email?: string;
orgId?: string;
roles: string[];
}) {
const grants = await delegatedGrantsForUser(user);
return createExternalAuthAssertion({
secret: process.env.AUGGY_EXTERNAL_AUTH_SECRET!,
keyId: "2026-07",
audience: "storefront-agent",
provider: "custom",
subject: user.id,
ttlSeconds: 60,
email: user.email,
emailVerified: true,
orgId: user.orgId,
roles: user.roles,
scopes: ["orders.read"],
grants,
authzVersion: "orders-v1",
jti: crypto.randomUUID(),
});
}Server only
Never put AUGGY_EXTERNAL_AUTH_SECRET in browser code. The generated browser client can forward an assertion through authAssertion, but the app backend must create it.
Route and tool requires
defineRoute.post("/orders/:id/refund", {
auth: "visitor.required",
params: z.object({ id: z.string() }),
body: z.object({ reason: z.string() }),
requires: { action: "refund.issue", resource: { param: "id" } },
handler: ({ params }) => json({ refundId: "refund_123", orderId: params.id }),
});defineTool({
name: "refund_order",
description: "Refund a customer order.",
category: "commerce",
input: z.object({
orderId: z.string(),
reason: z.string(),
}),
requires: {
action: "refund.issue",
resource: { input: "orderId" },
},
execute: async ({ orderId }) => "refund-started:" + orderId,
});