auth0-api-client/README.md

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

# 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 and GET request methods
- ⚡ Built-in error handling and response formatting
- 🛡️ Security best practices with token caching

## Installation

```bash
npm install
```

## Configuration

### Environment Variables

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

```bash
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

```javascript
const WebDataExporter = require('./index');

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 data via POST
const result = await client.postData('/endpoint', {
  key: 'value',
  data: 'example'
});

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

### POST Request

```javascript
const userData = {
  name: 'John Doe',
  email: 'john@example.com',
  action: 'user_created'
};

const result = await client.postData('/users', userData, {
  timeout: 10000, // Optional: custom timeout
  headers: {      // Optional: additional headers
    'X-Custom-Header': 'value'
  }
});
```

### Response Format

All methods return a standardized response object:

```javascript
// 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 */ }
  }
}
```

## 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

Both `postData` and `getData` methods accept an optional `options` parameter:

```javascript
{
  timeout: 30000,           // Request timeout in milliseconds
  headers: {},              // Additional headers
  params: {},               // Query parameters (GET only)
  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 example:

```bash
node example.js
```

## 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