Node.js SDK - Gately Documentation

The @gately/nodejs SDK provides JWT-based authentication for Node.js backends with first-class support for Express and Fastify.

Version: @gately/nodejs@2.4.0
Features: Token verification, Express middleware, Fastify plugin, token caching, TypeScript support

Installation

npm install @gately/nodejs@latest

Or install a specific version:

npm install @gately/nodejs@2.4.0

Get your API key: Dashboard → Settings → API Keys

Use a secret key (gately_sk_...) and keep it on your server. Token verification is rejected for public keys (gately_pk_...) and project IDs.

Quick Start

Express

import express from 'express'
import { gatelyMiddleware } from '@gately/nodejs/express'

const app = express()

app.use(gatelyMiddleware({
  apiKey: process.env.GATELY_API_KEY!
}))

app.get('/api/me', (req, res) => {
  res.json({ user: req.auth?.user })
})

app.listen(3000)

Fastify

import Fastify from 'fastify'
import { gatelyFastifyPlugin } from '@gately/nodejs/fastify'

const fastify = Fastify()

await fastify.register(gatelyFastifyPlugin, {
  apiKey: process.env.GATELY_API_KEY!
})

fastify.get('/api/me', async (request) => {
  return { user: request.auth?.user }
})

await fastify.listen({ port: 3000 })

Manual Token Verification

import { verifyToken } from '@gately/nodejs'

const user = await verifyToken(token, process.env.GATELY_API_KEY!)

console.log(user.sub)    // user ID
console.log(user.email)  // user email

Core API

verifyToken(token, apiKey, options?)

Verifies a Gately session token and returns its claims. Verification happens on Gately’s servers (POST /api/v1/auth/verify): the signature, expiry, and project are all checked, so a token is only accepted if Gately issued it to a member of the project that owns apiKey. Results are cached in memory for up to 5 minutes (never past the token’s expiry), so most requests don’t make a network call.

import { verifyToken, TokenVerificationError } from '@gately/nodejs'

try {
  const claims = await verifyToken(token, apiKey)
  // claims.sub        — member ID
  // claims.email      — member email
  // claims.project_id — project the member belongs to
  // claims.role       — member role
  // claims.iat        — issued at (unix seconds)
  // claims.exp        — expires at (unix seconds)
} catch (err) {
  if (err instanceof TokenVerificationError) {
    // invalid or expired token, token from another project,
    // invalid API key, or Gately couldn't be reached
  }
}

Option	Type	Default	Description
`apiUrl`	string	`process.env.GATELY_API_URL` or `https://api.usegately.com`	Gately API base URL

Versions before 2.4.0 decoded the token locally without checking its signature, and rejected real session tokens. Upgrade to 2.4.0 or later.

validateToken(token, apiKey)

Alias for verifyToken.

getAuthorizationHeader(authHeader)

Extracts the JWT from an Authorization header.

import { getAuthorizationHeader } from '@gately/nodejs'

const token = getAuthorizationHeader(req.headers.authorization)
// Handles: "Bearer <token>", "bearer <token>", or raw token

Express Integration

Global Middleware

import { gatelyMiddleware } from '@gately/nodejs/express'

app.use(gatelyMiddleware({
  apiKey: process.env.GATELY_API_KEY!,
  optional: false,                        // default — require auth
  excludePaths: ['/health', '/status']    // skip auth on these paths
}))

Per-Route: requireAuth

import { requireAuth } from '@gately/nodejs'

app.get('/api/profile', requireAuth(apiKey), (req, res) => {
  res.json({ user: req.auth?.user })
})

Per-Route: optionalAuth

Attaches user to req.auth if token is present, but doesn’t block if missing:

import { optionalAuth } from '@gately/nodejs'

app.get('/api/feed', optionalAuth(apiKey), (req, res) => {
  const isLoggedIn = !!req.auth?.user
  res.json({ personalised: isLoggedIn })
})

Per-Route: withAuth

Attach a custom callback after verification:

import { withAuth } from '@gately/nodejs'

app.delete('/api/users/:id',
  withAuth(apiKey, (user) => {
    if (user.role !== 'admin') throw new Error('Admins only')
  }),
  (req, res) => res.json({ deleted: true })
)

protect

Shorthand route-level protection:

import { protect } from '@gately/nodejs/express'

app.get('/api/secret', protect(apiKey), (req, res) => {
  res.json({ secret: '42' })
})

Fastify Integration

Plugin (Global)

import { gatelyFastifyPlugin } from '@gately/nodejs/fastify'

await fastify.register(gatelyFastifyPlugin, {
  apiKey: process.env.GATELY_API_KEY!,
  optional: false   // set true to make auth optional globally
})

Route-Level Protection

import { fastifyProtect } from '@gately/nodejs/fastify'

const guard = await fastifyProtect(fastify, apiKey)

fastify.get('/api/admin',
  { onRequest: guard.onRequest },
  async (request) => {
    return { user: request.auth?.user }
  }
)

Request Object

Middleware attaches an auth object to every authenticated request:

req.auth = {
  user: {
    sub: 'user_123',           // user ID
    email: 'user@example.com',
    apiKey: 'your_api_key',
    iat: 1694098800,
    exp: 1694102400,
    // ...any custom claims
  },
  token: 'eyJhbGc...'          // original JWT
}

Utility Functions

isTokenExpired

import { isTokenExpired } from '@gately/nodejs'

if (isTokenExpired(token)) {
  // token has expired
}

getTokenExpiry

import { getTokenExpiry } from '@gately/nodejs'

const secondsLeft = getTokenExpiry(token)
if (secondsLeft && secondsLeft < 300) {
  // expires in less than 5 minutes
}

Token Cache

Tokens are cached in memory to avoid re-decoding on every request:

import { clearTokenCache, getTokenCacheStats } from '@gately/nodejs'

// After revoking a token, clear cache
clearTokenCache()

// Check cache size
const { size, maxSize } = getTokenCacheStats()

Error Handling

import {
  GatelyError,
  TokenVerificationError,
  UnauthorizedError,
  ForbiddenError
} from '@gately/nodejs'

app.get('/api/data', async (req, res) => {
  try {
    const token = getAuthorizationHeader(req.headers.authorization)
    if (!token) throw new UnauthorizedError('Token required')

    const user = await verifyToken(token, apiKey)
    res.json({ user })
  } catch (err) {
    if (err instanceof TokenVerificationError) {
      return res.status(401).json({ error: 'Invalid or expired token' })
    }
    if (err instanceof UnauthorizedError) {
      return res.status(401).json({ error: err.message })
    }
    if (err instanceof ForbiddenError) {
      return res.status(403).json({ error: err.message })
    }
    res.status(500).json({ error: 'Server error' })
  }
})

Role-Based Access

function requireRole(role: string) {
  return (req: any, res: any, next: any) => {
    if (req.auth?.user?.role !== role) {
      return res.status(403).json({ error: 'Insufficient permissions' })
    }
    next()
  }
}

app.delete('/api/users/:id',
  requireAuth(apiKey),
  requireRole('admin'),
  handler
)

TypeScript

import type {
  AuthConfig,
  VerifiedToken,
  MiddlewareOptions,
  AuthRequest
} from '@gately/nodejs'

const config: AuthConfig = {
  apiKey: process.env.GATELY_API_KEY!
}

const handler = (req: AuthRequest, res: any) => {
  const user: VerifiedToken = req.auth!.user
  res.json({ id: user.sub, email: user.email })
}

Environment Variables

# .env
GATELY_API_KEY=your_api_key_here

const apiKey = process.env.GATELY_API_KEY
if (!apiKey) throw new Error('GATELY_API_KEY is not set')

Troubleshooting

Token verification fails

Confirm the token was issued by Gately and hasn’t expired
Ensure apiKey matches the project the token was issued for
Check the Authorization header format: Bearer <token>

Middleware not protecting routes

Middleware must be registered before route handlers:

// ✅ Correct
app.use(gatelyMiddleware({ apiKey }))
app.get('/api/data', handler)

// ❌ Wrong
app.get('/api/data', handler)
app.use(gatelyMiddleware({ apiKey }))

req.auth is undefined

Ensure the middleware ran successfully. Check that:

A valid Authorization: Bearer <token> header is sent
The route is not in excludePaths
optional is not set to true (which silently skips bad tokens)

Next Steps

React SDK

Client-side authentication

Next.js SDK

Full-stack Next.js auth

Support: support@usegately.com · Slack Community

​Installation

​Quick Start

​Express

​Fastify

​Manual Token Verification

​Core API

​verifyToken(token, apiKey, options?)

​validateToken(token, apiKey)

​getAuthorizationHeader(authHeader)

​Express Integration

​Global Middleware

​Per-Route: requireAuth

​Per-Route: optionalAuth

​Per-Route: withAuth

​protect

​Fastify Integration

​Plugin (Global)

​Route-Level Protection

​Request Object

​Utility Functions

​isTokenExpired

​getTokenExpiry

​Token Cache

​Error Handling

​Role-Based Access

​TypeScript

​Environment Variables

​Troubleshooting

​Next Steps

React SDK

Next.js SDK

Installation

Quick Start

Express

Fastify

Manual Token Verification

Core API

verifyToken(token, apiKey, options?)

validateToken(token, apiKey)

getAuthorizationHeader(authHeader)

Express Integration

Global Middleware

Per-Route: requireAuth

Per-Route: optionalAuth

Per-Route: withAuth

protect

Fastify Integration

Plugin (Global)

Route-Level Protection

Request Object

Utility Functions

isTokenExpired

getTokenExpiry

Token Cache

Error Handling

Role-Based Access

TypeScript

Environment Variables

Troubleshooting

Next Steps