Facebook Login

Facebook Login signs people in to your app with their Facebook account. @mayurajs/auth-facebook offers two ways to use it with Mayura:

• facebookAuthenticator: Facebook Login user access tokens sent straight to Mayura's server, checked with Facebook's debug_token endpoint, and optionally iOS Limited Login tokens, checked with Facebook's published keys. Your identity mapping decides what each user may do.
• facebookSignIn: Facebook as a social login for better-auth, reading no more of the profile than signing in needs.

It talks to Facebook with fetch and verifies Limited Login tokens with mayura/auth's own JWT verifier (WebCrypto only): no Facebook SDK, no dependency, and it runs on every runtime Mayura runs on.

#Install

npm install mayura @mayurajs/auth-facebook

#Credentials

Your App ID and App Secret are on your app's App settings > Basic page in Meta for Developers. facebookAuthenticator needs both: access tokens are opaque, so it asks Facebook about each one with your app's token (<appId>|<appSecret>). The secret stays on your server and never appears in an error.

The package reads nothing from the environment: pass the values in yourself, for example from FACEBOOK_APP_ID and FACEBOOK_APP_SECRET.

#Use it

import { principalId } from 'mayura/auth';
import { facebookAuthenticator } from '@mayurajs/auth-facebook';

export const authenticate = facebookAuthenticator({
  appId: process.env.FACEBOOK_APP_ID ?? '',
  appSecret: process.env.FACEBOOK_APP_SECRET ?? '',
  requiredScopes: ['email'],
  identity: session => ({
    principalId: principalId('facebook', session.userId),
    projectId: 'acme',
    agentIds: ['support'],
    capabilities: ['runs:submit', 'runs:read'],
  }),
});
// createAgentServer({ ..., authenticate })

Clients send the user access token from the Facebook SDK as the bearer token. session.userId is app-scoped: the same person has a different id in each of your apps.

To have users sign in to your own application with better-auth instead, pass facebookSignIn as its Facebook provider:

import { betterAuth } from 'better-auth';
import { facebookSignIn } from '@mayurajs/auth-facebook';

export const auth = betterAuth({
  socialProviders: {
    facebook: facebookSignIn({
      clientId: process.env.FACEBOOK_APP_ID ?? '',
      clientSecret: process.env.FACEBOOK_APP_SECRET ?? '',
    }),
  },
});

#Options

facebookAuthenticator:

facebookSignIn:

facebookSignIn reads only the id, name and email fields (picture if asked), and asks for no permissions beyond better-auth's email and public_profile unless you add scopes.

#Access tokens

A token that looks like a Facebook Login user access token (EA and letters and digits) is sent to https://graph.facebook.com/<graphVersion>/debug_token with your app token. It passes only when Facebook says it is valid, a user's (type USER), for your app, not expired, and holds every permission in requiredScopes.

• What leaves your server. The user's token and your app token, in the query string of the call to graph.facebook.com. Nothing else is sent.
• A call per request. With cacheTtlMs at 0, each request asks Facebook, so a token the user revokes stops at once. A higher cacheTtlMs keeps Facebook's answer, refusals too, for that long (in up to 10,000 entries keyed by the token's SHA-256), and a revoked token then works for that long more.
• Expiry. The identity ends with the token's expires_at. A token Facebook says never expires still lasts no longer than maxIdentityMs before it is checked again.

#Limited Login

With limitedLogin: true, tokens from iOS Limited Login, which are OIDC JWTs, are checked with no call per request: RS256 with Facebook's keys from https://www.facebook.com/.well-known/oauth/openid/jwks/, issued by https://www.facebook.com, for your app ID, with exp required and clockSkewMs of leeway, and with a sub. Check the token's nonce in your app, which made it. Without limitedLogin, these tokens are not accepted and never make it fetch keys.

#What identity receives

#Errors

#How it is tested

• Unit tests run the package against a fake debug_token endpoint that checks the app token on every call. They check that invalid, other-app, non-user, expired and under-permissioned tokens are refused, that answers are kept only with cacheTtlMs, that unreachable, failing and malformed answers become TOOL_FAILED without the app secret in any message, that cancellation and timeoutMs stop the call, and that Limited Login tokens are verified with signed test tokens only when limitedLogin is on.
• scripts/live/auth-facebook.mjs fetched and checked Facebook's published Limited Login signing keys on October 6,
  2026. A real token has not been verified with it yet.

#Related

• Authentication and API keys: the verifier, key caching and identity mapping.
• Sign-in with better-auth: sign-in on your own database.
• Google sign-in: another consumer sign-in, with a better-auth preset.