🎫Use Basic Auth with Dispatcher

Learn how to use HTTP Basic Authentication to make Dispatcher API requests.

Overview

Once you've created your Basic Auth header (see Authentication), include it in every Dispatcher API request.

Authentication Flow:

1. Create Basic Auth header: Authorization: Basic <base64(email:password)>
2. Include header in all Dispatcher API requests
3. No token expiration or refresh needed

Basic Usage

Authorization Header

Every Dispatcher API request requires the Authorization header:

Authorization: Basic <base64_encoded_credentials>

Full request example:

POST /api/invoicing HTTP/1.1
Host: api.docs-dispatcher.io
Authorization: Basic b2xpdmllci5yb2VsYW50c0BnbWFpbC5jb206eW91ci1wYXNzd29yZA==
Content-Type: application/json

{
  "providerName": "qonto",
  "documentType": "INVOICE",
  "template": {
    "id": 123,
    "data": { /* template data */ }
  }
}

Code Examples

curl

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

# Method 2: Pre-encode credentials
export EMAIL="[email protected]"
export PASSWORD="your-password"
export 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 @invoice-request.json

Node.js (fetch)

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

// Store credentials securely
const email = process.env.DOCS_DISPATCHER_EMAIL;
const password = process.env.DOCS_DISPATCHER_PASSWORD;
const authHeader = createBasicAuthHeader(email, password);

// Make API request
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: {
      id: 123,
      data: { /* template data */ }
    }
  })
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(`Dispatch failed: ${error.message}`);
}

const result = await response.json();
console.log(result);

PHP (Guzzle)

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

use GuzzleHttp\Client;

// Store credentials securely
$email = $_ENV['DOCS_DISPATCHER_EMAIL'];
$password = $_ENV['DOCS_DISPATCHER_PASSWORD'];

$client = new Client();

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

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

} catch (\GuzzleHttp\Exception\ClientException $e) {
    $error = json_decode($e->getResponse()->getBody(), true);
    echo "Dispatch 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) {
        // Create Basic Auth header
        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("Dispatch failed: " + response.body());
        }

        return response.body();
    }
}

// Usage
DispatcherClient client = new DispatcherClient(
    System.getenv("DOCS_DISPATCHER_EMAIL"),
    System.getenv("DOCS_DISPATCHER_PASSWORD")
);

String result = client.dispatchInvoice(requestJson);

Authentication Errors

401 Unauthorized

Error Response:

{
  "error": "unauthorized",
  "message": "Invalid credentials"
}

Common Causes:

1. Wrong Credentials

   # ❌ Wrong - typo in email/password
   curl -u "[email protected]:wrongpassword" ...

   Solution: Verify email and password are correct

2. Missing Authorization Header

   # ❌ Wrong - missing header
   curl -X POST https://api.docs-dispatcher.io/api/invoicing

   # ✅ Correct - includes authorization
   curl -X POST https://api.docs-dispatcher.io/api/invoicing \
     -u "[email protected]:password"

3. Malformed Header

   # ❌ Wrong - missing "Basic" prefix
   -H "Authorization: b2xpdmllci5yb2VsYW50c0BnbWFpbC5jb206..."
   
   # ✅ Correct - includes "Basic" prefix
   -H "Authorization: Basic b2xpdmllci5yb2VsYW50c0BnbWFpbC5jb206..."

4. Encoding Issues

   // ❌ Wrong - not base64 encoded
   const authHeader = `Basic ${email}:${password}`;
   
   // ✅ Correct - base64 encoded
   const credentials = `${email}:${password}`;
   const authHeader = `Basic ${Buffer.from(credentials).toString('base64')}`;

403 Forbidden

Error Response:

{
  "error": "forbidden",
  "message": "Insufficient permissions for this operation"
}

Common Causes:

1. User Lacks Permissions

   • User role doesn't allow this service

   • Solution: Contact admin to grant permissions

2. Company Configuration Missing

   • Provider not configured for your company

   • Solution: Set up provider config in admin panel

3. IP Whitelist Restriction

   • Request from non-whitelisted IP

   • Solution: Contact support to update IP whitelist

Reusable Client Class

Node.js

class DispatcherClient {
  constructor(email, password) {
    this.authHeader = this.createBasicAuthHeader(email, password);
    this.baseUrl = 'https://api.docs-dispatcher.io/api';
  }

  createBasicAuthHeader(email, password) {
    const credentials = `${email}:${password}`;
    const base64 = Buffer.from(credentials).toString('base64');
    return `Basic ${base64}`;
  }

  async request(endpoint, method = 'POST', data = null) {
    const options = {
      method,
      headers: {
        'Authorization': this.authHeader,
        'Content-Type': 'application/json'
      }
    };

    if (data) {
      options.body = JSON.stringify(data);
    }

    const response = await fetch(`${this.baseUrl}${endpoint}`, options);

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`HTTP ${response.status}: ${error.message}`);
    }

    return await response.json();
  }

  async dispatchInvoice(requestData) {
    return this.request('/invoicing', 'POST', requestData);
  }

  async dispatchEmail(requestData) {
    return this.request('/email', 'POST', requestData);
  }

  async validateInvoice(requestData) {
    return this.request('/invoicing/validate', 'POST', requestData);
  }
}

// Usage
const client = new DispatcherClient(
  process.env.DOCS_DISPATCHER_EMAIL,
  process.env.DOCS_DISPATCHER_PASSWORD
);

const result = await client.dispatchInvoice({
  providerName: 'qonto',
  documentType: 'INVOICE',
  template: { /* ... */ }
});

PHP

<?php

class DispatcherClient {
    private $client;
    private $email;
    private $password;
    private $baseUrl = 'https://api.docs-dispatcher.io/api';

    public function __construct($email, $password) {
        $this->email = $email;
        $this->password = $password;
        $this->client = new \GuzzleHttp\Client();
    }

    private function request($endpoint, $method = 'POST', $data = null) {
        $options = [
            'auth' => [$this->email, $this->password]
        ];

        if ($data !== null) {
            $options['json'] = $data;
        }

        try {
            $response = $this->client->request(
                $method,
                $this->baseUrl . $endpoint,
                $options
            );

            return json_decode($response->getBody(), true);
        } catch (\GuzzleHttp\Exception\ClientException $e) {
            $error = json_decode($e->getResponse()->getBody(), true);
            throw new Exception($error['message'], $e->getResponse()->getStatusCode());
        }
    }

    public function dispatchInvoice($requestData) {
        return $this->request('/invoicing', 'POST', $requestData);
    }

    public function dispatchEmail($requestData) {
        return $this->request('/email', 'POST', $requestData);
    }

    public function validateInvoice($requestData) {
        return $this->request('/invoicing/validate', 'POST', $requestData);
    }
}

// Usage
$client = new DispatcherClient(
    $_ENV['DOCS_DISPATCHER_EMAIL'],
    $_ENV['DOCS_DISPATCHER_PASSWORD']
);

$result = $client->dispatchInvoice([
    'providerName' => 'qonto',
    'documentType' => 'INVOICE',
    'template' => [ /* ... */ ]
]);

Best Practices

1. Credential Management

Reuse credentials efficiently:

// ✅ Good - create header once, reuse many times
const authHeader = createBasicAuthHeader(email, password);

// Make multiple requests with same header
await fetch(endpoint1, { headers: { Authorization: authHeader } });
await fetch(endpoint2, { headers: { Authorization: authHeader } });
await fetch(endpoint3, { headers: { Authorization: authHeader } });

// ❌ Bad - recreating header for each request
await fetch(endpoint1, {
  headers: {
    Authorization: createBasicAuthHeader(email, password)
  }
});
await fetch(endpoint2, {
  headers: {
    Authorization: createBasicAuthHeader(email, password)
  }
});

2. Error Handling

Always handle authentication errors:

async function dispatchWithErrorHandling(endpoint, data) {
  try {
    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. Check email and password.');
    }

    if (response.status === 403) {
      throw new Error('Insufficient permissions for this operation.');
    }

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Request failed: ${error.message}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Dispatch error:', error);
    throw error;
  }
}

3. Secure Storage

Never hardcode credentials:

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

// ✅ Good - environment variables
const email = process.env.DOCS_DISPATCHER_EMAIL;
const password = process.env.DOCS_DISPATCHER_PASSWORD;

// ✅ Good - config file (gitignored)
const config = require('./config.json');
const email = config.email;
const password = config.password;

// ✅ Best - secret management service
const email = await secretsManager.getSecret('dispatcher-email');
const password = await secretsManager.getSecret('dispatcher-password');

4. Never Log Credentials

// ❌ NEVER log credentials or auth headers
console.log('Email:', email);
console.log('Password:', password);
console.log('Auth header:', authHeader);

// ✅ Good - log without exposing credentials
console.log('Email: [REDACTED]');
console.log('Auth header: [REDACTED]');
console.log('Authenticating with Basic Auth');

Debugging Authentication

Test Your Credentials

# Simple health check with authentication
curl -X GET https://api.docs-dispatcher.io/healthz \
  -u "[email protected]:your-password"

# Expected: 200 OK
# If 401: Credentials are invalid

Verify Base64 Encoding

# Encode credentials
echo -n "[email protected]:password" | base64

# Decode to verify
echo "ZW1haWxAY29tcGFueS5jb206cGFzc3dvcmQ=" | base64 -d
# Should output: [email protected]:password

Check Header Format

// Verify header format
const authHeader = createBasicAuthHeader(email, password);
console.log('Auth header format:', authHeader.substring(0, 10));
// Should output: "Basic b2xp..."

// Verify it starts with "Basic "
if (!authHeader.startsWith('Basic ')) {
  console.error('Invalid header format - missing "Basic " prefix');
}

Security Considerations

1. HTTPS Only

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

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

2. Browser Security

// ❌ NEVER call Dispatcher API from browser
// This exposes your credentials to XSS attacks

// ✅ Use backend proxy pattern
Browser → Your Backend API → Dispatcher API
         (no credentials)    (with Basic Auth)

3. Credential Rotation

• Change passwords every 90 days

• Use strong, unique passwords (min 12 characters)

• Never share credentials across environments

• Revoke access immediately when no longer needed

Next Steps

Now that you understand Basic Authentication:

1. Quickstart Guide - Send your first invoice

2. Core Concepts - Understand provider configuration

3. Invoice Recipe - Full dispatch example with code

Support

• Authentication issues: [email protected]

• Credential management: See Troubleshooting