Your product's session

If your customers already sign in to your product, the docs can trust that session. There is no second sign-in and no separate docs account. On every request, the docs server reads your product's session cookie and verifies it with your auth provider.

How it worksCopy Anchor Link

1. A reader opens a restricted page. The server looks for your product's session cookie.
2. If the cookie is there and valid, the reader is in. Their groups come from a claim in the session.
3. If not, they see the sign-in page with Continue with <name>. It sends them to your loginUrl with ?redirect_to=<page URL>.
4. They sign in to your product, which sets its cookie and sends them back. The docs now see the cookie.
5. Sign out in the docs goes to your logoutUrl (or loginUrl when there is none). Your product ends its own session.

Verified sessions are cached in memory by a hash of the cookie. Token sessions are re-checked when they expire and at least every 5 minutes; Appwrite sessions every minute.

Requirements for your sign-in pageCopy Anchor Link

loginUrl must:

• Read the return URL from the redirect_to query parameter, or the parameter you set in returnParam.
• Accept the docs origin as a return target. The value is a full URL, such as https://docs.acme.com/internal/runbook/.
• Send readers who are already signed in straight back to that URL. The docs don't refresh expired tokens, so readers whose token expired come through here again.

SupabaseCopy Anchor Link

access: {
  groups: { partners: { idpGroups: ['partner'] } },
  rules: [{ path: '/partners/*', groups: ['partners'] }],
  appSession: {
    type: 'supabase',
    name: 'Acme account',
    projectUrl: 'https://abcd1234.supabase.co',
    loginUrl: 'https://app.acme.com/login',
    logoutUrl: 'https://app.acme.com/logout',
  },
},

Set groups from your backend with the service role key. app_metadata can't be changed by the user:

await supabase.auth.admin.updateUserById(userId, {
  app_metadata: { groups: ['partner'] },
});

Your app must use @supabase/ssr (or set the same cookie) so the session is in a cookie, not only in local storage. Supabase access tokens last one hour by default.

ClerkCopy Anchor Link

appSession: {
  type: 'clerk',
  domain: 'clerk.acme.com',
  loginUrl: 'https://accounts.acme.com/sign-in',
  returnParam: 'redirect_url',
  secretKeyEnv: 'CLERK_SECRET_KEY',
},

returnParam: 'redirect_url' matches Clerk's hosted sign-in page (Account Portal).

FirebaseCopy Anchor Link

appSession: {
  type: 'firebase',
  projectId: 'acme-prod',
  loginUrl: 'https://app.acme.com/login',
},

The Firebase client SDK keeps tokens in browser storage, not cookies. Your app's server must set __session itself. Session cookies are the better choice: they last up to two weeks, while ID tokens expire after an hour.

const cookie = await getAuth().createSessionCookie(idToken, { expiresIn: 7 * 24 * 3600 * 1000 });
res.cookie('__session', cookie, { domain: '.acme.com', httpOnly: true, secure: true, sameSite: 'lax' });

// Groups for the docs:
await getAuth().setCustomUserClaims(uid, { groups: ['partner'] });

AppwriteCopy Anchor Link

appSession: {
  type: 'appwrite',
  endpoint: 'https://cloud.appwrite.io/v1',
  projectId: '65f0c0ffee',
  loginUrl: 'https://app.acme.com/login',
},

Use Appwrite's server-side rendering pattern: your app creates the session with a server SDK and sets a_session_<projectId> on your own domain (the parent domain, if the docs are on a subdomain).

OptionsCopy Anchor Link

Shared by every type:

Per type:

Combine with SSOCopy Anchor Link

appSession and providers work together. The sign-in page shows your product's button first, then "or", then the SSO buttons. A reader can have both; the docs session from SSO is checked first.

Next stepsCopy Anchor Link