🔐Authentication

Learn how to authenticate with Dispatcher API using Basic Authentication.

Overview

Docs-Dispatcher uses HTTP Basic Authentication for all API requests. This is a simple and secure method where you send your credentials with each request.

Authentication Flow:

1. Encode your email:password as base64
2. Add Authorization: Basic <base64> header to each request
3. Make Dispatcher API requests

graph LR
    A[Your App] -->|Basic Auth Header| B[Dispatcher API]
    B -->|Service Response| A

Basic Authentication Header

Header Format

All API requests must include the Authorization header with Basic authentication:

Authorization: Basic <base64(email:password)>

How to Create the Header

1. Concatenate your email and password with a colon: email:password

2. Encode the string as base64

3. Prefix with Basic

Example:

Email: [email protected]
Password: your-password

String to encode: [email protected]:your-password
Base64 encoded: b2xpdmllci5yb2VsYW50c0BnbWFpbC5jb206eW91ci1wYXNzd29yZA==

Header: Authorization: Basic b2xpdmllci5yb2VsYW50c0BnbWFpbC5jb206eW91ci1wYXNzd29yZA==

Response (Success)

When credentials are valid, the API responds with the requested data (200 OK).

Response (Error)

Invalid Credentials (401):

{
  "error": "unauthorized",
  "message": "Invalid email or password"
}

Missing Authorization Header (401):

{
  "error": "unauthorized",
  "message": "Authorization header required"
}

Code Examples

curl

# Method 1: Let curl handle Basic Auth encoding
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -u "[email protected]:your-password" \
  -H "Content-Type: application/json" \
  -d @request.json

# Method 2: Manually encode and set header
EMAIL="[email protected]"
PASSWORD="your-password"
AUTH_HEADER=$(echo -n "$EMAIL:$PASSWORD" | base64)

curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Basic $AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d @request.json

Node.js (fetch)

// Create Basic Auth header
function createBasicAuthHeader(email, password) {
  const credentials = `${email}:${password}`;
  const base64Credentials = Buffer.from(credentials).toString('base64');
  return `Basic ${base64Credentials}`;
}

// Use in requests
const email = '[email protected]';
const password = 'your-password';
const authHeader = createBasicAuthHeader(email, password);

const response = await fetch('https://api.docs-dispatcher.io/api/invoicing', {
  method: 'POST',
  headers: {
    'Authorization': authHeader,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    providerName: 'qonto',
    documentType: 'INVOICE',
    template: { /* ... */ }
  })
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const result = await response.json();

PHP (Guzzle)

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$email = '[email protected]';
$password = 'your-password';

$client = new Client();

try {
    $response = $client->post('https://api.docs-dispatcher.io/api/invoicing', [
        'auth' => [$email, $password],  // Guzzle handles Basic Auth encoding
        'json' => [
            'providerName' => 'qonto',
            'documentType' => 'INVOICE',
            'template' => [ /* ... */ ]
        ]
    ]);

    $result = json_decode($response->getBody(), true);
    print_r($result);

} catch (\GuzzleHttp\Exception\ClientException $e) {
    $error = json_decode($e->getResponse()->getBody(), true);
    echo "Request failed: " . $error['message'];
}

Java (HttpClient)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class DispatcherClient {
    private final String authHeader;
    private final HttpClient client;

    public DispatcherClient(String email, String password) {
        String credentials = email + ":" + password;
        String base64Credentials = Base64.getEncoder()
            .encodeToString(credentials.getBytes());
        this.authHeader = "Basic " + base64Credentials;
        this.client = HttpClient.newHttpClient();
    }

    public String dispatchInvoice(String requestJson) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/api/invoicing"))
            .header("Authorization", authHeader)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestJson))
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        if (response.statusCode() != 200) {
            throw new Exception("Request failed: " + response.body());
        }

        return response.body();
    }
}

Encoding Base64

Command Line (bash)

# Linux/Mac
echo -n "[email protected]:password" | base64

# Output: ZW1haWxAY29tcGFueS5jb206cGFzc3dvcmQ=

Node.js

const credentials = '[email protected]:password';
const base64 = Buffer.from(credentials).toString('base64');
console.log(base64);
// Output: ZW1haWxAY29tcGFueS5jb206cGFzc3dvcmQ=

PHP

<?php
$credentials = '[email protected]:password';
$base64 = base64_encode($credentials);
echo $base64;
// Output: ZW1haWxAY29tcGFueS5jb206cGFzc3dvcmQ=

Java

import java.util.Base64;

String credentials = "[email protected]:password";
String base64 = Base64.getEncoder().encodeToString(credentials.getBytes());
System.out.println(base64);
// Output: ZW1haWxAY29tcGFueS5jb206cGFzc3dvcmQ=

No Token Expiration: Unlike JWT tokens, Basic Auth credentials don't expire. You send them with every request. This simplifies authentication but requires secure credential storage.

Security Best Practices

1. Never Hardcode Credentials

❌ Bad:

const email = '[email protected]';
const password = 'mysecretpassword'; // NEVER do this

✅ Good:

const email = process.env.DOCS_DISPATCHER_EMAIL;
const password = process.env.DOCS_DISPATCHER_PASSWORD;

2. Store Credentials Securely

Backend (Node.js/Java/PHP):

• Environment variables

• Encrypted configuration files

• Secret management services (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault)

Browser:

• ❌ Never store credentials in localStorage/sessionStorage

• ❌ Never expose credentials to browser JavaScript

• ✅ Use backend proxy for all Dispatcher calls

Example secure pattern:

Browser → Your Backend API → Dispatcher API
         (no credentials)    (with Basic Auth)

3. Use HTTPS Only

All API requests must use HTTPS. HTTP requests will be rejected.

// ❌ NEVER use HTTP
const url = 'http://api.docs-dispatcher.io/...';

// ✅ Always use HTTPS
const url = 'https://api.docs-dispatcher.io/...';

4. Rotate Credentials Regularly

• Change passwords every 90 days

• Revoke unused API access

• Audit user access periodically

• Use strong, unique passwords (min 12 characters)

5. Handle Authentication Errors

Always check for 401 responses:

async function dispatchWithAuth(endpoint, data, email, password) {
  const authHeader = createBasicAuthHeader(email, password);

  const response = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Authorization': authHeader,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (response.status === 401) {
    throw new Error('Invalid credentials');
  }

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  return response.json();
}

Common Authentication Errors

401 Unauthorized

Causes:

• Wrong email or password

• Missing Authorization header

• Incorrectly formatted Basic Auth header

Solutions:

• Verify credentials are correct

• Check header format: Authorization: Basic <base64>

• Ensure credentials are properly base64 encoded

• Test credentials with -u flag in curl

Debug example:

# Test your credentials
curl -X GET https://api.docs-dispatcher.io/healthz \
  -u "[email protected]:your-password"

# If valid: 200 OK
# If invalid: 401 Unauthorized

403 Forbidden

Causes:

• User lacks permissions for the requested service

• IP whitelist restriction

Solutions:

• Contact admin to grant necessary permissions

• Verify IP is whitelisted (if IP restrictions enabled)

429 Rate Limit

Causes:

• Too many requests (>100/minute per user)

Solutions:

• Add rate limiting to your application

• Implement exponential backoff for retries

• Cache results when possible

Next Steps

Now that you understand Basic Authentication:

1. Use Basic Auth with Dispatcher - Complete authentication guide

2. Quickstart Guide - Send an invoice using validation endpoint

3. Invoice Recipe - Generate and dispatch a real invoice

Support

• Authentication issues: [email protected]

• Password reset: Contact support

• Account access: [email protected]