version: "1.0.1" name: auth-setup description: Use when configuring OAuth providers (Google/GitHub/Apple/X/etc.), setting up post-login auth hooks, tuning JWT lifetimes, or generating service API keys

Butterbase Auth Setup

Two umbrella tools cover end-user authentication:

• `manage_oauth` — provider configuration (Google, GitHub, Apple, X, custom)
• `manage_auth_config` — auth hooks, JWT lifetimes, service key generation

For broad app build-out, see also butterbase:build-app. This skill is the deep dive.

1. The role model

Every request runs under one of three database roles:

Auth is what transforms a request into the right role. RLS is what filters the data. Both must be configured.

2. Configure an OAuth provider

manage_oauth({
  app_id: "app_abc123",
  action: "configure",
  provider: "google",
  client_id: "123456789.apps.googleusercontent.com",
  client_secret: "GOCSPX-...",
  redirect_uris: ["https://api.butterbase.ai/auth/app_abc123/oauth/google/callback"]
  // scopes / authorization_url / token_url / userinfo_url / provider_metadata are auto-filled for built-in providers
})

Built-in providers (URLs and scopes pre-filled): google, github, discord, facebook, linkedin, microsoft, apple, x.

Custom providers: pass authorization_url, token_url, userinfo_url, and scopes explicitly.

Redirect URI format

https://api.butterbase.ai/auth/{app_id}/oauth/{provider}/callback

Register this exact URI in the provider's developer console. Mismatch is the most common reason OAuth flows fail.

Provider quirks

List, update, delete

manage_oauth({ app_id, action: "get" })                          // list all providers (secrets redacted)
manage_oauth({ app_id, action: "get", provider: "google" })      // single provider
manage_oauth({ app_id, action: "update", provider: "google", client_secret: "new-secret" })
manage_oauth({ app_id, action: "delete", provider: "google" })   // disables future logins; existing sessions valid until expiry

Frontend flow

GET https://api.butterbase.ai/auth/{app_id}/oauth/{provider}?redirect_to=https://yourapp.com/auth/callback

User signs in at the provider, gets bounced back to redirect_to with access_token and refresh_token as query params. The Butterbase SDK wraps this:

await client.auth.signInWithOAuth({ provider: "google" });
const { user, accessToken } = await client.auth.getSession();

3. Tune JWT lifetimes

manage_auth_config({
  app_id: "app_abc123",
  action: "update_jwt",
  accessTokenTtl: "15m",       // formats: "15m", "1h", "2h", "1d"
  refreshTokenTtlDays: 30      // integer days
})

Defaults: 15-minute access tokens, 7-day refresh tokens.

Important: changes apply only to new tokens. Active tokens keep their original expiration — there is no global revoke. Treat TTL changes as forward-looking only.

4. Auth hooks (run code after every login)

A post-auth function is a deployed Butterbase function invoked fire-and-forget after every successful auth event (OAuth login, email login, email signup).

Wire it up

// 1. Deploy the function first (see butterbase:function-dev)
deploy_function({
  app_id: "app_abc123",
  name: "after-auth",
  code: postAuthHandlerCode,
  trigger: { type: "http", config: { auth: "none" } }
})
// 2. Register it as the auth hook
manage_auth_config({
  app_id: "app_abc123",
  action: "configure_auth_hook",
  post_auth_function: "after-auth"
})
// To remove the hook later: pass post_auth_function: null

The function must already exist when you configure the hook.

Payload shape

The function receives a POST with this body:

{
  "event": "oauth_login | login | signup",
  "user": {
    "id": "uuid",
    "email": "...",
    "provider": "google | github | email | ...",
    "display_name": "...",
    "avatar_url": "..."
  },
  "isNewUser": true,
  "provider": "google"
}

The function runs as butterbase_service (RLS bypassed, ctx.user is null). Use body.user.id to know who just logged in.

Common uses

// after-auth/index.ts
export async function handler(req, ctx) {
  const { user, isNewUser, event } = await req.json();
  if (isNewUser) {
    // 1. Create profile row
    await ctx.db.query(
      "INSERT INTO profiles (user_id, display_name) VALUES ($1, $2) ON CONFLICT DO NOTHING",
      [user.id, user.display_name]
    );
    // 2. Send welcome email (via env-stored API key)
    ctx.waitUntil(sendWelcomeEmail(ctx.env.RESEND_API_KEY, user.email));
  }
  // 3. Audit log on every login
  await ctx.db.query(
    "INSERT INTO login_log (user_id, event, provider) VALUES ($1, $2, $3)",
    [user.id, event, ctx.user ?? null]
  );
  return new Response("ok", { status: 200 });
}

Auth hooks are fire-and-forget. Don't return data the user needs — they won't see it. Use them for side effects only.

5. Service keys (bb_sk_*)

Service keys grant full access to all your apps and bypass RLS. Treat them like passwords.

Generate

manage_auth_config({
  action: "generate_service_key",
  name: "CI/CD pipeline"
})
// → { key: "bb_sk_a1b2c3...", key_id, prefix, name, created_at }

The full key is returned once. Store it immediately in your secret manager — you cannot retrieve it again. If you lose it, generate a new one and revoke the old.

List & revoke

manage_api_keys({ action: "list" })
manage_api_keys({ action: "revoke", key_id: "uuid-..." })

list returns metadata only (prefix, name, last_used_at), never the secret. revoke is immediate and irreversible.

Rotation workflow

1. manage_auth_config (generate_service_key) — create the new key.
2. Update CI/CD, MCP config, scripts to use the new key.
3. Verify with a smoke test (e.g. manage_app list).
4. manage_api_keys (revoke) — kill the old key.

Do steps 1–3 before step 4 to avoid downtime.

6. Anti-patterns

7. Quick reference

If a docs/butterbase/00-state.md exists in the working directory, prefer invoking via /butterbase:journey-auth so the journey orchestrator stays in sync.