Authentication

Flux API uses API key authentication to secure access to your content delivery endpoints. This method provides secure access through asymmetric encryption without requiring user credentials.

Overview

Unlike the Management API which always requires authentication, Flux API authentication is optional and can be configured per API instance through the Management API.

Key Differences from Management API

Authentication Configuration

Flux API authentication is controlled through the Management API when creating or updating your API instance:

• Public APIs: Set authentication to false for open content delivery
• Private APIs: Set authentication to true to require API keys

This flexibility allows you to create both public content APIs and secure private APIs using the same infrastructure.

When Authentication is Required

When authentication is enabled for your Flux API, all requests must include valid API credentials. API keys are generated through the Dashboard and use asymmetric encryption with public-private key pairs for maximum security.

API Key Authentication

When you create an API key, you receive:

• Public Key: Used to identify your API key and verify signatures
• Private Key: Used to sign requests and must be kept secret

Both keys are provided in Base64 encoding. The private key is shown only once during creation, so store it securely.

Authentication Methods

Flux API supports two authentication methods:

1. Secure Method - Uses digital signatures
2. Simple Method - Basic authentication

Secure Authentication

The secure method uses ECDSA digital signatures to ensure request integrity and authenticity.

How It Works

1. Prepare data to sign:

   data_to_sign = "<uri>|<body_hash>|<timestamp>"
   

   CopyCopied!

2. Create signature:

   • Sign data_to_sign with your private key using ECDSA-SHA256

3. Set headers:

   Authorization: Secure <public_key>:<signature>
   Date: <timestamp>
   

   CopyCopied!

Required Elements

Example Implementation

Complete example showing secure authentication for a search request.

const crypto = require('crypto');

const publicKey = 'your-public-key';
const privateKey = 'your-private-key';
const uri = '/your-api-prefix/your-folder-alias/7c9h4pwu/another-folder-alias/_search';
const body = JSON.stringify({
  "where": {
    "$": {
      "all_of": [
        {"status__eq": "published"}
      ]
    }
  }
});

// Calculate body hash
const bodyHash = crypto
  .createHash('sha256')
  .update(body)
  .digest('hex');

// Generate timestamp
const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');

// Create data to sign
const dataToSign = `${uri}|${bodyHash}|${timestamp}`;

// Sign the data
const privateKeyBuffer = Buffer.from(privateKey, 'base64');
const sign = crypto.createSign('SHA256');
sign.update(dataToSign);
const signature = sign.sign(privateKeyBuffer, 'base64');

// Make request
const headers = {
  'Authorization': `Secure ${publicKey}:${signature}`,
  'Date': timestamp,
  'Content-Type': 'application/json'
};

fetch(`https://7c9h4pwu.fxns.io${uri}`, {
  method: 'POST',
  headers: headers,
  body: body
})
.then(response => response.json())
.then(data => console.log(data));

Important Notes

• Time synchronization is critical - see API Limits for authentication timeout requirements
• URI path must include the API prefix (e.g., /your-api-prefix/...)
• Empty body requires SHA-256 hash of empty string

Simple Authentication

For easier implementation, use the simple method which directly includes both keys in the Authorization header.

Simple Method Format

No signatures or timestamps required - just include both keys in the header.

Authorization: Simple <public_key>:<private_key>

Example Implementation

  const publicKey = 'your-public-key';
  const privateKey = 'your-private-key';

  const headers = {
    'Authorization': `Simple ${publicKey}:${privateKey}`,
    'Content-Type': 'application/json'
  };

  fetch('https://7c9h4pwu.fxns.io/api-prefix/articles/_search', {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({
      "where": {
        "$": {
          "all_of": [
            {"status__eq": "published"}
          ]
        }
      }
    })
  })
  .then(response => response.json())
  .then(data => console.log(data));