Provider OAuth configuration

OAuth providers redirect to Authlane, where state, PKCE, token exchange, encrypted storage, and refresh stay inside the control plane.

Prerequisites

Create separate development and production provider applications and choose the minimum required provider scopes.

Implement the workflow

1. Register the exact callback https://app.authlane.io/api/v1/oauth/{serviceId}/callback, replacing {serviceId} with a shipped ID such as github.
2. For local development, use http://localhost:3000/api/v1/oauth/{serviceId}/callback.
3. Enable the service in the Authlane dashboard and store its client ID, encrypted client secret, and approved custom scopes. Services the platform already holds credentials for are available in every workspace without this step; registering your own application replaces the platform one, and switching a service off in the dashboard keeps it off.
4. Create a short-lived session from your authenticated SaaS backend:

import { Authlane } from '@authlane/sdk';

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

export async function connectGithub(userId: string) {
  const { data, error } = await authlane.connectSessions.create({
    externalUserId: userId,
    allowedServices: ['github'],
    allowedOrigin: 'https://app.example.com',
    expiresInSeconds: 600,
  });
  if (error) {
    return { data: null, error };
  }
  return { data: data.url, error: null };
}

Use allowedServices: [] only when you intend to snapshot every currently enabled tenant service.

Expected result

The hosted UI starts authorization with single-use state and PKCE, receives the callback on the Authlane origin, stores credentials encrypted, and reports the result to the exact parent origin.

Handle errors

For denied consent, show a retry action. For state mismatch or token exchange failure, discard the flow and start with a new connect session. Confirm the exact callback, client credentials, provider scope approval, and public HTTPS origin.

Security boundary

Provider client secrets, refresh tokens, and ID tokens never reach your widget or SaaS frontend. Disconnect requires a newly minted connect session after fresh user authentication, with reauthenticatedAt set to that trusted time.

Next step

Implement connection lifecycle and lifecycle webhooks.