Authentication

Reeflow APIs support two authentication methods for server-to-server requests. Both methods are secure and officially supported—choose the one that best fits your implementation needs.

Authentication Methods

Basic Authentication

The simplest way to authenticate with Reeflow APIs. Send your API key credentials using standard HTTP Basic authentication.

Best for:

• Quick integration and testing
• Simple scripts and tools
• Client libraries that support HTTP Basic auth out of the box

Example:

GET /connections HTTP/1.1
Host: api.reeflow.com
Authorization: Basic a2V5X2FiYzEyM3h5ejpza19zZWNyZXRfeHl6Nzg5

Note: The authorization header contains key_abc123xyz:a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789abc base64 encoded

HMAC Signature Mode

More secure authentication using HMAC-SHA256 signatures with timestamp validation and replay protection.

Best for:

• Production environments requiring maximum security
• Applications handling sensitive data
• Long-running services where secret exposure is a concern

Example:

POST /connections HTTP/1.1
Host: api.reeflow.com
X-API-Key: key_abc123xyz
X-API-Timestamp: 1730930400
X-API-Signature: a1b2c3d4e5f6...
Content-Type: application/json

Security Comparison

While both methods are secure and suitable for production use, here’s how they compare:

Security Feature	Basic Authentication	HMAC Signature Mode
Secret in Transit	API secret is base64 encoded in every request header (visible if decoded)	Secret never leaves your server—only the signature is sent
Replay Attack Protection	❌ Requests can be replayed if intercepted	✅ Timestamp validation prevents replay attacks (5-minute window)
Request Integrity	❌ Request body can be modified without detection	✅ Any modification to method, path, timestamp, or body invalidates the signature
Temporal Security	❌ Compromised credentials remain valid until rotated	✅ Each request has a limited time window for validity
Implementation Complexity	✅ Simple - standard HTTP Basic auth	❌ Complex - requires signature generation logic
Client Library Support	✅ Supported by all HTTP clients out of the box	❌ Requires custom implementation or specialized libraries
Debugging Difficulty	✅ Easy to inspect and test with curl/Postman	❌ Harder to debug - requires signature calculation

When to Choose Each Method

Choose Basic Authentication when:

• Building prototypes or internal tools
• Working with trusted networks
• Prioritizing development speed
• Need simple integration (all requests are automatically encrypted via HTTPS)

Choose HMAC Signature Mode when:

• Handling production workloads
• Processing sensitive customer data
• Requiring audit trails with tamper evidence
• Implementing financial or healthcare applications

Getting Started

Both authentication methods use the same API key credentials that you generate in the Reeflow Console.

What you’ll need

API credentials (from your Reeflow Console):

• API key ID (starts with key_)
• API key secret (64-character random string)

Quick Start Examples

Basic Authentication

// HTTP Basic authentication
const credentials = Buffer.from(`${API_KEY_ID}:${API_KEY_SECRET}`).toString('base64');
const response = await fetch('https://api.reeflow.com/connections', {
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  method: 'GET',
});

HMAC Signature Mode

// HMAC signature authentication (requires signing logic)
import { createHmac } from 'node:crypto';

const timestamp = Math.floor(Date.now() / 1000).toString();
const canonical = ['GET', '/connections', timestamp, '', ''].join('\n');
const signature = createHmac('sha256', API_KEY_SECRET).update(canonical).digest('hex');

const response = await fetch('https://api.reeflow.com/connections', {
  headers: {
    'X-API-Key': API_KEY_ID,
    'X-API-Timestamp': timestamp,
    'X-API-Signature': signature,
  },
  method: 'GET',
});

Detailed Guides

Ready to implement authentication? Choose your preferred method for complete setup instructions:

• Basic Authentication - Start here for the fastest integration
• HMAC Signature Mode - Complete guide to secure HMAC authentication

Common Rules

Both authentication methods follow these important guidelines:

• Choose one method per request: Never send both Authorization and X-API-Key headers
• HTTPS enforced: All API requests are automatically encrypted with TLS/SSL
• Store secrets securely: Use environment variables or secure vaults for API credentials
• Handle errors gracefully: Implement retry logic with exponential backoff for network issues