@civic/auth-verify

​

Features

​

When to Use

​

✅ Perfect For

• Microservices Architecture: Verify tokens in individual services without full SDK overhead
• Serverless Functions: Minimal bundle size and fast cold starts for AWS Lambda, Vercel Functions, etc.
• API Gateways: Token validation at the edge before reaching your application
• Background Workers: Verify user context in queued jobs and background processes
• Third-party Integrations: Validate Civic Auth tokens in external services or webhooks

​

❌ Use Other Solutions If

• You need complete authentication flows (login/logout) - use full Civic Auth SDK
• Building React/Next.js applications - use @civic/auth or @civic/auth-web3
• Need session management and user state handling

​

Prerequisites

• For Civic Auth tokens: No setup required - works out of the box
• For other issuers: Ensure your issuer exposes a .well-known/openid-configuration endpoint
• For audience validation: You’ll need the expected audience value from your token issuer

​

Getting Civic Auth Credentials (if needed)

1. Visit auth.civic.com
2. Sign up or log in to your account
3. Create a new application to obtain your Client ID
4. Use the Client ID with the clientId parameter when verifying tokens

​

Installation

npm install @civic/auth-verify

​

Quick Start

import { verify } from '@civic/auth-verify';

// Verify a token (uses Civic Auth issuer by default)
try {
  const payload = await verify(token);
  console.log('User ID:', payload.sub);
  console.log('Email:', payload.email);
  console.log('Name:', payload.name);
} catch (error) {
  console.error('Token verification failed:', error);
}

​

Cache Options

​

Default In-Memory Cache

import { verify, InMemoryJWKSCache } from '@civic/auth-verify';

// Create a custom cache instance
const cache = new InMemoryJWKSCache();

// Use the cache for verification
const payload = await verify(token, {
  jwksCache: cache
});

​

Bundled Cache (Offline Support)

import { verify, BundledJWKSCache } from '@civic/auth-verify';

// Use bundled cache with pre-downloaded Civic Auth JWKS
const cache = new BundledJWKSCache();

const payload = await verify(token, {
  jwksCache: cache
});

• ⚡ Zero network latency for Civic Auth tokens
• 🚀 Perfect for serverless cold starts
• 📦 Keys bundled at build time
• 🔄 Automatic fallback to network fetch for other issuers

​

API Reference

​

verify(token, options?)

• token (string): The JWT token to verify
• options (object, optional):
  • issuer (string): Token issuer URL (defaults to https://auth.civic.com/oauth/). The library automatically appends /.well-known/openid-configuration to discover OIDC configuration.
  • wellKnownConfigurationUrl (string): Custom OpenID configuration URL (overrides automatic discovery)
  • jwksCache (JWKSCache): Custom JWKS cache implementation
  • aud (string): Expected audience value (typically the identity provider URL)
  • clientId (string): Expected client ID - validates against client_id or tid fields in the JWT payload

​

Cache Classes

• InMemoryJWKSCache: Default in-memory cache with automatic cleanup
• BundledJWKSCache: Pre-loaded cache with Civic Auth JWKS for offline verification

​

Configuration Examples

​

Multiple Issuers

import { verify } from '@civic/auth-verify';

// Verify Civic Auth token (uses default issuer)
const civicUser = await verify(civicToken);

// Verify token from custom issuer
// This will fetch OIDC configuration from:
// https://custom-auth.example.com/.well-known/openid-configuration
const customUser = await verify(customToken, {
  issuer: 'https://custom-auth.example.com'
});

​

Client ID Validation

import { verify } from '@civic/auth-verify';

// Verify token and ensure it's for your specific client
const payload = await verify(token, {
  clientId: 'your-civic-client-id'
});

​

Audience Validation

import { verify } from '@civic/auth-verify';

// Verify token with expected audience (typically the issuer)
const payload = await verify(token, {
  aud: 'https://auth.civic.com/oauth/'
});

​

Error Handling

import { verify } from '@civic/auth-verify';

try {
  const payload = await verify(token);
} catch (error) {
  // The library throws errors with descriptive messages for various scenarios:
  // - Invalid/expired tokens
  // - Network failures (OIDC/JWKS fetch)
  // - Key not found in JWKS
  // - Client ID mismatches (client_id or tid)
  // - Audience mismatches (aud claim)
  console.error('Token verification failed:', error.message);
  
  // Handle verification failure appropriately for your application
  // (redirect to login, return 401, etc.)
}

​

Key Benefits

​

Best Practices

1. Reuse Cache Instances: Create cache instances once and reuse them across requests
2. Handle Errors Gracefully: Implement proper error handling for different failure scenarios
3. Use Bundled Cache: For maximum performance with Civic Auth tokens
4. Validate Audience: Always specify expected audience for production applications

​

Next Steps

• Integration Guides - Full authentication flows
• Recipes (coming soon) - Practical implementation examples
• npm Package - Package details and versions