🔐 ars-facebook-auth

Lightweight Facebook access token verification for Node.js and TypeScript

Validate a Facebook user access token, confirm that it belongs to your app, and receive a normalized user profile through one typed function.

Contents

• Features
• Installation
• TypeScript usage
• NestJS usage
• API reference
• Error handling
• Requirements
• Security
• License

✨ Features

• Validates Facebook user access tokens
• Confirms that a token was issued for your Facebook app
• Generates appsecret_proof using your app secret
• Fetches the user's ID, name, email, and profile picture
• Normalizes missing profile fields to null
• Supports custom Facebook Graph API versions
• Provides TypeScript types with no runtime dependencies

📦 Installation

npm install ars-facebook-auth

import { verifyFacebookToken } from 'ars-facebook-auth';

const profile = await verifyFacebookToken(accessToken, {
  appId: process.env.FACEBOOK_APP_ID!,
  appSecret: process.env.FACEBOOK_APP_SECRET!,
});

console.log(profile);

Example response:

{
  id: '123456789',
  name: 'Jane Doe',
  email: '[email protected]',
  picture: 'https://platform-lookaside.fbsbx.com/...'
}

ars-facebook-auth has no NestJS dependency. You can wrap it in an injectable service and keep your Facebook credentials in server-side configuration.

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import {
  verifyFacebookToken,
  type FacebookProfile,
} from 'ars-facebook-auth';

@Injectable()
export class FacebookAuthService {
  constructor(private readonly configService: ConfigService) {}

  verify(accessToken: string): Promise<FacebookProfile> {
    return verifyFacebookToken(accessToken, {
      appId: this.configService.getOrThrow<string>('FACEBOOK_APP_ID'),
      appSecret: this.configService.getOrThrow<string>('FACEBOOK_APP_SECRET'),
    });
  }
}

🧰 API reference

verifyFacebookToken(accessToken, options)

Validates the supplied access token and returns its associated Facebook profile. The function rejects with an Error if validation or profile fetching fails.

function verifyFacebookToken(
  accessToken: string,
  options: FacebookAuthOptions,
): Promise<FacebookProfile>;

Configuration

• appId — Facebook app ID. Required.
• appSecret — Facebook app secret. Required.
• graphVersion — Facebook Graph API version. Optional; defaults to v19.0.

type FacebookAuthOptions = {
  appId: string;
  appSecret: string;
  graphVersion?: string;
};

Returned profile

type FacebookProfile = {
  id: string;
  name: string | null;
  email: string | null;
  picture: string | null;
};

[!NOTE] email may be null because Facebook does not always return it. Other unavailable optional profile fields are also normalized to null.

🛟 Error handling

import { verifyFacebookToken } from 'ars-facebook-auth';

try {
  const profile = await verifyFacebookToken(accessToken, {
    appId: process.env.FACEBOOK_APP_ID!,
    appSecret: process.env.FACEBOOK_APP_SECRET!,
  });

  console.log(profile);
} catch (error: unknown) {
  const message =
    error instanceof Error ? error.message : 'Facebook authentication failed';

  console.error(message);
}

Errors are thrown when required values are missing, a token is invalid, a token belongs to another app, or Facebook profile retrieval fails.

✅ Requirements

• Node.js 18 or later with the global fetch API available
• A Facebook app ID and app secret
• A Facebook user access token issued for the configured app

🛡️ Security

[!WARNING] FACEBOOK_APP_SECRET must never be exposed to frontend or client-side code.

• Call this package only from a trusted server environment.
• Store app credentials in environment variables or a secrets manager.
• Never commit app credentials or access tokens to source control.
• Treat user access tokens as sensitive data and avoid logging them.

📄 License

Released under the MIT License © 2026 A R S.