Auth0 API Client

A Node.js module for making authenticated API calls using Auth0 Machine-to-Machine (M2M) JWT tokens.

Features

• 🔐 Auth0 M2M authentication with automatic token management
• 🔄 Automatic token refresh with expiry handling
• 📡 POST request methods with event support
• ⚡ Built-in error handling and response formatting
• 🛡️ Security best practices with token caching
• 📊 Support for Auth0 event types (login, logout, signup, etc.)

Installation

npm install

Configuration

Environment Variables

Copy .env.example to .env and configure your Auth0 and API settings:

cp .env.example .env

Auth0 Setup

1. Create a Machine-to-Machine application in your Auth0 dashboard
2. Configure the application with the necessary scopes for your API
3. Note down the Domain, Client ID, Client Secret, and Audience

Usage

Basic Usage

const { WebDataExporter, EventType } = require('./src/index.js');

const client = new WebDataExporter({
  auth0Domain: 'your-domain.auth0.com',
  auth0ClientId: 'your-client-id',
  auth0ClientSecret: 'your-client-secret',
  auth0Audience: 'https://your-api-audience',
  apiBaseUrl: 'https://your-api.example.com'
});

// Send an Auth0 event
const event = {
  message: 'User logged in successfully',
  timestamp: new Date(),
  eventType: EventType.LOGIN
};

const result = await client.postData('/events', event);

if (result.success) {
  console.log('Success:', result.data);
} else {
  console.error('Error:', result.error);
}

Using the Auth0Event Class

const { WebDataExporter, EventType, Auth0Event } = require('./src/index.js');

const client = new WebDataExporter({
  // ... config
});

// Create an event using the class
const event = new Auth0Event(
  'User profile updated',
  new Date(),
  EventType.PROFILE_UPDATE
);

const result = await client.postData('/events', event);

POST Request with Options

const event = {
  message: 'User action completed',
  timestamp: new Date(),
  eventType: EventType.API_ACCESS
};

const result = await client.postData('/events', event, {
  timeout: 10000, // Optional: custom timeout
  headers: {      // Optional: additional headers
    'X-Custom-Header': 'value',
    'X-Flow-ID': 'custom-flow-123'
  }
});

Available Event Types

const { EventType } = require('./src/index.js');

// All available event types
console.log(EventType.LOGIN);        // 'login'
console.log(EventType.LOGOUT);       // 'logout'
console.log(EventType.SIGNUP);       // 'signup'
console.log(EventType.PASSWORD_CHANGE); // 'password_change'
console.log(EventType.PROFILE_UPDATE);  // 'profile_update'
console.log(EventType.API_ACCESS);      // 'api_access'

Response Format

All methods return a standardized response object:

// Success response
{
  success: true,
  data: { /* API response data */ },
  status: 200,
  headers: { /* response headers */ }
}

// Error response
{
  success: false,
  error: {
    message: 'Error description',
    status: 400, // HTTP status (if available)
    data: { /* error details from API */ },
    type: 'network_error' // Error type
  }
}

Configuration Options

| Option | Required | Description | |--------|----------|-------------| | auth0Domain | Yes | Your Auth0 domain (e.g., 'your-domain.auth0.com') | | auth0ClientId | Yes | M2M application Client ID | | auth0ClientSecret | Yes | M2M application Client Secret | | auth0Audience | Yes | API audience identifier | | apiBaseUrl | Yes | Base URL of your target API |

Request Options

The postData method accepts an optional options parameter:

{
  timeout: 30000,           // Request timeout in milliseconds
  headers: {},              // Additional headers
  axiosConfig: {}           // Additional axios configuration
}

Error Handling

The module handles three types of errors:

1. API Errors: When the API responds with an error status
2. Network Errors: When no response is received
3. Unknown Errors: Other unexpected errors

Token Management

• Tokens are automatically cached and reused until expiry
• Automatic refresh when tokens expire
• 5-minute safety buffer before token expiry
• Use client.clearToken() to force token refresh

Testing

Run the tests:

npm test

Run the example:

node example.js

Examples

• example.js - Basic usage examples
• auth0-action-example.js - Auth0 Actions integration examples

Security Notes

• Never commit your .env file or expose credentials
• Use environment variables for sensitive configuration
• The module automatically handles token security and expiry
• Tokens are cached in memory only (not persisted)

License

MIT