OAuth

Use OAuth authentication with the Fathom SDKs

OAuth Authentication

OAuth users need to register an app with us before using this feature. Visit our OAuth Setup Guide to get your client credentials and configure your redirect URL.

Both TypeScript and Python SDKs support OAuth 2.0 authentication for building integrations that can be installed by multiple Fathom accounts.

Step 1: Get Authorization URL

Using the Client ID and Client Secret you received when registering your app, generate an authorization URL that users will visit to grant your app access:

TypeScript

import { Fathom } from 'fathom-typescript';

const url = Fathom.getAuthorizationUrl({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUri: 'https://your_redirect_url',
  scope: 'public_api',
  state: 'randomState123',
});

// Redirect user to this URL
console.log(url);

Step 2: Handle OAuth Callback

After the user authorizes your app, they’ll be redirected back to your redirect URI with an authorization code. Use this code to exchange it for access tokens:

TypeScript

import { Fathom } from 'fathom-typescript';

// User gets redirected here with code
const tokenStore = Fathom.newTokenStore();
const fathom = new Fathom({
  security: Fathom.withAuthorization({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    code: "AUTHORIZATION_CODE_FROM_CALLBACK",
    redirectUri: "https://your_redirect_url",
    tokenStore: tokenStore
  }),
});

// Now you can make requests and we'll refresh the token if needed
const result = await fathom.listMeetings({});

Complete OAuth Flow Example

Here’s a complete example showing both steps:

TypeScript

import { Fathom } from 'fathom-typescript';

// Step 1: Generate authorization URL
const clientId = "your_client_id";
const clientSecret = "your_client_secret";
const redirectUri = "https://your-app.com/oauth/callback";
const scope = "public_api";
const state = "random_state_string";

const authUrl = Fathom.getAuthorizationUrl({
  clientId,
  clientSecret,
  redirectUri,
  scope,
  state,
});

console.log(`Redirect user to: ${authUrl}`);

// Step 2: Handle the callback (this would be in your callback endpoint)
async function handleOAuthCallback(authorizationCode: string) {
  const tokenStore = Fathom.newTokenStore();
  
  const fathom = new Fathom({
    security: Fathom.withAuthorization({
      clientId,
      clientSecret,
      code: authorizationCode,
      redirectUri,
      tokenStore
    }),
  });
  
  // Now you can make API calls
  const meetings = await fathom.listMeetings({});
  return meetings;
}

OAuth Handler Examples

Complete OAuth flow implementations for web frameworks:

Express.js

import express from 'express';
import { Fathom } from 'fathom-typescript';

const app = express();

// OAuth initiation endpoint
app.get('/auth/fathom', (req, res) => {
  const authUrl = Fathom.getAuthorizationUrl({
    clientId: process.env.FATHOM_CLIENT_ID!,
    clientSecret: process.env.FATHOM_CLIENT_SECRET!,
    redirectUri: 'https://your-app.com/auth/fathom/callback',
    scope: 'public_api',
    state: 'random_state_string',
  });
  
  res.redirect(authUrl);
});

// OAuth callback endpoint
app.get('/auth/fathom/callback', async (req, res) => {
  const { code, state } = req.query;
  
  if (!code || typeof code !== 'string') {
    return res.status(400).send('Authorization code required');
  }
  
  try {
    const tokenStore = Fathom.newTokenStore();
    const fathom = new Fathom({
      security: Fathom.withAuthorization({
        clientId: process.env.FATHOM_CLIENT_ID!,
        clientSecret: process.env.FATHOM_CLIENT_SECRET!,
        code,
        redirectUri: 'https://your-app.com/auth/fathom/callback',
        tokenStore
      }),
    });
    
    // Test the connection
    const meetings = await fathom.listMeetings({});
    res.json({ success: true, meetingsCount: meetings.items?.length || 0 });
  } catch (error) {
    console.error('OAuth error:', error);
    res.status(500).send('OAuth authentication failed');
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Token Management

The SDK automatically handles token refresh when needed. The tokenStore manages the access and refresh tokens for you.

OAuth Scopes

Currently, the only available scope is:

• public_api - Access to the Fathom API

For more information about setting up OAuth applications, see our OAuth Setup Guide.