Authorization providers

An authorization provider is a plain object in the authorization key of better-supabase.config.ts. It tells better-supabase which SQL functions answer "does this user hold this permission", which scopes exist, which membership tables the provider reads, and which claims its access token hook writes. better-supabase never imports the provider: the object is data, and the provider's own package builds it, usually from the files that package generates.

import { defineConfig } from "better-supabase/config";
import { authorizationProvider } from "your-authorization-package";

export default defineConfig({
  authorization: authorizationProvider(),
  sql: { modules: { access: { model: "provider" }, organizations: {} } },
});

PermDock builds one from its manifest and catalog.

The provider covers the database side. Permission checks in your server code (a resource's permissions, an action's or MCP tool's permission, a route guard) go to a runtime authorizer instead, passed as authorizer to the server. An authorization package can ship both: the provider for the config, and an authorizer for the server that answers with the same permission keys.

What reads itCopy Anchor Link

entitlements.memberships defaults to "provider" when authorization is set. The access model stays what sql.modules.access.model says.

The contractCopy Anchor Link

interface AuthorizationProvider {
  apiVersion: 1;
  name: string;
  scopes: { name: string; idType?: string; parent?: string }[];
  tenantScope: string;
  functions: AuthorizationFunctions;
  requires?: { function: string; args?: string; role: string }[];
  permissions?: { key: string; sqlComplete?: boolean; scopes?: string[] }[];
  memberships?: {
    table: string;
    userColumn: string;
    scope: { column: string } | { value: string };
    idColumn: string;
  }[];
  suspension?: { user?: DisabledRow; tenant?: DisabledRow };
  roleSources?: AuthorizationRoleSource[];
  decidingColumns?: string[];
  tokenHook?: AuthorizationTokenHook;
  approvals?: { distinctApprover?: boolean };
  problems?: string[];
}

AuthorizationProvider and its parts are exported from better-supabase/config. A scope name is lower case ([a-z][a-z0-9_]*), because it goes into templates unquoted. problems lists what the provider found wrong while building the object; doctor reports each one.

The CLI validates the object when it loads the config. Every scope name in tenantScope and parent must be declared, parents must not form a cycle, the tenant scope needs an idType, and idType is uuid, text, bigint or integer. Each decidingColumns entry is schema.table.column, and tokenHook.budget.bytes is a positive integer. An object with another apiVersion gets one message naming both versions instead of a list of field errors.

FunctionsCopy Anchor Link

Each function is a SQL template. better-supabase fills the placeholders and puts the result into a policy or a module function:

idsWith and isPlatform are required. A template that leaves out a For variant makes the module function answer for the caller only: called for another user, it raises SQLSTATE 0A000. Without canAssign, only the service role assigns roles: the access module's can_assign answers false for every member, owners included.

Some modules call the optional templates under the provider model: invitations calls idsWithFor, isPlatformFor and canAssignFor to check the inviter again when an invitation is accepted; inbox, comments, sso, notifications, connectors and workflow-sdk-world call idsWithFor; and usage reads memberships through memberIds. Doctor (BS411) warns for each installed module whose template the provider doesn't set.

permissionsFor fills better_supabase.member_permissions and permission_claims, so the access token hook can carry permission keys. The claims cover the tenants memberIdsFor returns; without memberIdsFor they stay empty. Without permissionsFor, both functions return nothing, as before.

functions: {
  idsWith: "authz.{scope}_ids_with({permission})",
  isPlatform: "authz.is_platform({permission})",
  memberIds: "authz.member_{scope}_ids()",
  canAssign: "authz.can_assign({role}, {tenant}::text)",
},
requires: [
  { function: "authz.organization_ids_with", args: "text", role: "authenticated" },
  { function: "authz.is_platform", args: "text", role: "authenticated" },
  { function: "authz.member_organization_ids", role: "authenticated" },
  { function: "authz.can_assign", args: "text, text", role: "authenticated" },
],

requires lists every function the templates call, with {scope} filled, and the role that must be able to execute it. Doctor (BS411) checks the database has each one, and the conformance block checks the list is complete. idType is the Postgres type of a scope's ids: uuid, text, bigint or integer.

PermissionsCopy Anchor Link

permissions lists the keys the provider knows. sqlComplete: true says its SQL functions answer the key completely: a grant has no row condition beyond the scope. Bucket and topic policies and the SQL modules check by role and scope only, so gen, sql add and doctor (BS214, BS411) refuse a key that isn't marked. Leave row-conditioned keys to the provider's table policies.

Token hookCopy Anchor Link

tokenHook describes the custom access token hook the provider generates:

Tool approvalsCopy Anchor Link

canApprove decides who may approve or deny a waiting AI tool call in the ai-chat block. Under the provider model, decide_ai_tool_approval lets the service role and any caller canApprove allows decide the call; {tenant} is the chat's tenant and {tool} the tool's name. approvals.distinctApprover: true keeps the chat's owner, whose agent asked for the call, from deciding it, for four-eyes approval. Without canApprove, the chat's owner decides.

functions: {
  // ...
  canApprove: "authz.can_approve_tool({tool}, {tenant}::text)",
},
approvals: { distinctApprover: true },

Bucket and topic policiesCopy Anchor Link

An access policy calls the access contract (tenant_ids_with, is_platform) by default. Give it the provider's templates in sql, and it calls those instead, for any scope they take. sql: "provider" uses the provider's idsWith and isPlatform: better-supabase gen writes them into the generated bucket meta, and better-supabase sql sync passes them to each topic's sql(). A copy of the templates also works, so the bucket module doesn't import the config; doctor (BS214) warns when the copy differs from the provider.

import { defineBucket } from "better-supabase/storage";

export const documents = defineBucket({
  id: "documents",
  path: "{organizationId}/{documentId}/{name}",
  policy: {
    access: { read: "documents.browse", write: "documents.write" },
    scope: "organization",
    sql: "provider",
  },
});

A topic with sql: "provider" throws when its sql() runs without templates. Pass them yourself outside sql sync:

topic.sql({ functions: config.authorization.functions });

The scope id is compared as text, so a path or topic segment must be the id's lowercase form. segment picks another path segment than {organizationId}.

Test a providerCopy Anchor Link

testAuthorizationProvider from better-supabase/testing checks API v1, plain JSON, valid scopes (known names, no parent cycle, a tenant scope with an idType), the placeholders of each template (each uses its {permission}, {user}, {tenant} and {role}, and idsWith and idsWithFor use {scope} when there is more than one scope), that templates are safe to inline (no function call without a schema, no $$, ; or --), that requires lists every function the templates call, the permission list, and the shapes of memberships, suspension, roleSources, decidingColumns and tokenHook: ownedClaims is not empty, a registeredClaims entry is not also owned, budget.claims are owned or registered, and budget.bytes is a positive integer. See conformance blocks.

import { testAuthorizationProvider } from "better-supabase/testing";
import { it } from "vitest";

it("conforms", () => testAuthorizationProvider(authorizationProvider()));

A provider for a new contract version sets another apiVersion; this release refuses anything but 1 with a message naming both versions.