Load user-scoped tools

Turn one user's effective capability snapshot into framework-native callbacks inside your SaaS.

Prerequisites

Install @authlane/sdk, @authlane/ai, and the optional peer for your framework. Authenticate the user before this server code runs.

Implement the workflow

import { vercelAI } from '@authlane/ai/vercel';
import { Authlane } from '@authlane/sdk';
import { streamText, type ModelMessage } from 'ai';

const authlane = new Authlane({ apiKey: process.env.AUTHLANE_API_KEY! });

export async function runForUser(userId: string, messages: ModelMessage[]) {
  const { data: tools, error } = await authlane.user(userId).tools.list({
    // The framework asks the user before running anything that changes data.
    adapter: vercelAI({ approval: 'write-and-destructive' }),
  });
  if (error) return { data: null, error };

  const stream = streamText({ model: 'openai/gpt-5-mini', messages, tools });
  return { data: stream, error: null };
}

Binding authlane.user(userId) comes before adapter selection. The capability read builds only definitions and callbacks. Each callback requests a fresh lease when it is invoked.

Tool safety metadata

Every canonical tool includes MCP annotations:

• readOnlyHint identifies retrieval without provider mutation.
• destructiveHint identifies delete or equivalent irreversible operations.
• idempotentHint describes whether repeating a mutation has the same effect.
• openWorldHint signals that the tool communicates with an external provider.

Authlane derives risk: 'read' | 'write' | 'destructive' and preserves both the annotations and risk in MCP and OpenAI responses. Missing or invalid annotations fail closed instead of being treated as read-only.

The tenant chooses Read-only tools or Full tool set independently for every service in the dashboard. Read-only filtering happens in the control plane before definitions reach your SDK. Changing a policy invalidates affected connections so the next OAuth grant uses the matching scope set.

Adapter approval policies are separate from service filtering:

Tools discovered from the provider

Most services run an MCP server of their own, and Authlane already prefers it when a tool runs: GitHub calls go to api.githubcopilot.com, Attio's to mcp.attio.com. Those servers offer far more than Authlane hand-writes — GitHub declares eight tools in the catalog and its official endpoint reports 47 — so Authlane asks each one for its full catalogue and offers the rest alongside the canonical tools.

Two things follow from how that list is trusted.

A tool Authlane declares keeps its reviewed annotations. The provider's own claim about the same tool does not override them, because a server that labelled a delete as read-only would otherwise reach a read-only connection.

A tool only the provider offers counts as a mutation. It cannot be reviewed at discovery time, and trusting readOnlyHint from a third party is exactly the failure the reviewed annotations exist to prevent. A read-only service therefore offers precisely the canonical tools it always did — discovery adds nothing to it. Set the service to the full tool set to reach the wider surface.

Discovery runs in the background, twice a day, and never on the path that lists tools: listing issues no credentials, and asking a provider requires an access token. A provider that is unreachable changes nothing — the last catalogue stands, and a service that has never been discovered simply offers the canonical tools.

Expected result

tools is native to the selected framework and permanently scoped to this user snapshot.

Handle errors

Return the SDK tuple error from the control-plane read. Adapter callbacks expose fixed redacted errors to the model instead of provider response bodies or credentials.

Security boundary

Never serialize or share the executable toolset, cache it across users, or accept the external user ID from model arguments. Provider execution stays in the SaaS runtime and bypasses Authlane.

Discovering a provider's catalogue sends that user's access token to the provider's own MCP endpoint, the same endpoint their tool calls already reach. Nothing else leaves Authlane, and a discovered catalogue is stored per organization, never shared between tenants.

Next step

Choose a complete flow under SDKs and frameworks.