OAuth 2.0 Flow Guide¶

const { oauth } = ContioPartnerSDK.forUser({
  clientId: process.env.CONTIO_CLIENT_ID!,
  clientSecret: process.env.CONTIO_CLIENT_SECRET!,
  redirectUri: 'https://your-app.com/callback'
});

// Generate authorization URL with state for CSRF protection
const state = crypto.randomUUID();
req.session.oauthState = state;

const authUrl = oauth.getAuthorizationUrl(state, [
  'openid',
  'profile',
  'meetings:read',
  'action-items:read'
]);

res.redirect(authUrl);

// Generate authorization URL with login_hint for known email
const authUrl = oauth.getAuthorizationUrl(state, scopes, {
  login_hint: 'user@example.com'
});

app.get('/callback', async (req, res) => {
  const { code, state, error, error_description } = req.query;

  // Check for errors
  if (error) {
    console.error('OAuth error:', error, error_description);
    return res.redirect('/error?message=' + encodeURIComponent(error_description as string));
  }

  // Verify state to prevent CSRF
  if (state !== req.session.oauthState) {
    return res.status(400).send('Invalid state parameter');
  }

  try {
    // Exchange code for tokens
    const tokens = await oauth.exchangeCodeForToken(code as string);

    // Store tokens securely (encrypted)
    await saveUserTokens(req.session.userId, tokens);

    res.redirect('/dashboard');
  } catch (error) {
    console.error('Token exchange failed:', error);
    res.redirect('/error');
  }
});

async function getValidTokens(userId: string): Promise<OAuthTokens> {
  const tokens = await loadUserTokens(userId);

  // Check if access token is expired (with 5 min buffer)
  const expiresAt = tokens.issued_at + (tokens.expires_in * 1000);
  const isExpired = Date.now() > expiresAt - (5 * 60 * 1000);

  if (isExpired) {
    const newTokens = await oauth.refreshToken(tokens.refresh_token);
    await saveUserTokens(userId, newTokens);
    return newTokens;
  }

  return tokens;
}

// Using the SDK
const introspection = await oauth.introspectToken(accessToken);

if (introspection.active) {
  console.log('Token is valid');
  console.log('Subject:', introspection.sub);
  console.log('Scopes:', introspection.scope);
  console.log('Expires:', new Date(introspection.exp * 1000));
} else {
  console.log('Token is invalid or expired');
}

try {
  const tokens = await oauth.exchangeCodeForToken(code);
} catch (error) {
  switch (error.code) {
    case 'invalid_grant':
      // Code expired or already used - restart flow
      return res.redirect('/connect');
    case 'invalid_client':
      // Bad credentials - check configuration
      console.error('Invalid client credentials');
      break;
    case 'session_expired':
      // OTP session expired - user needs to re-authenticate
      return res.redirect('/connect?error=session_expired');
  }
}

async function refreshTokenMiddleware(req: Request, res: Response, next: NextFunction) {
  if (!req.session.refreshToken) {
    return next();
  }

  const tokenExpiresAt = req.session.tokenExpiresAt || 0;
  const bufferTime = 5 * 60 * 1000; // 5 minutes buffer

  // Check if token is expired or about to expire
  if (Date.now() >= tokenExpiresAt - bufferTime) {
    try {
      const tokenResponse = await oauth.refreshAccessToken(req.session.refreshToken);

      // Update session with new tokens
      req.session.accessToken = tokenResponse.access_token;
      req.session.refreshToken = tokenResponse.refresh_token;
      req.session.tokenExpiresAt = Date.now() + (tokenResponse.expires_in * 1000);

      console.log('Token refreshed successfully');
    } catch (error) {
      console.error('Token refresh failed:', error);
      // Clear invalid tokens
      delete req.session.accessToken;
      delete req.session.refreshToken;
      delete req.session.tokenExpiresAt;
    }
  }

  next();
}

// Apply to all authenticated routes
app.use(refreshTokenMiddleware);

app.post('/auth/logout', async (req, res) => {
  // Revoke token at Contio
  if (req.session.accessToken) {
    try {
      await oauth.revokeToken(req.session.accessToken);
    } catch (error) {
      console.error('Token revocation failed:', error);
      // Continue with logout even if revocation fails
    }
  }

  // Destroy session
  req.session.destroy((err) => {
    if (err) {
      console.error('Session destruction error:', err);
    }
    res.redirect('/');
  });
});

import { createHash, randomBytes } from 'crypto';

function generatePKCE() {
  const verifier = randomBytes(32).toString('base64url');
  const challenge = createHash('sha256')
    .update(verifier)
    .digest('base64url');

  return { verifier, challenge };
}

// During authorization
const { verifier, challenge } = generatePKCE();
req.session.codeVerifier = verifier;

const authUrl = oauth.getAuthorizationUrl({
  state,
  code_challenge: challenge,
  code_challenge_method: 'S256'
});

// During token exchange
const tokenResponse = await oauth.exchangeCodeForToken(code, {
  code_verifier: req.session.codeVerifier
});