Authentication Guide

This guide explains how to authenticate with the Recommand Peppol API using API keys.

Creating API Keys

To interact with the Recommand Peppol API, you need an API key and secret:

1. Log in to your Recommand dashboard
2. Navigate to Account > API Keys
3. Provide a descriptive name for your key (e.g., "Production Integration")
4. Click Create API Key

The system will display your API key and secret. Your secret is displayed only once so store it securely as you won't be able to retrieve the secret again.

API Key: key_aBcDeFgHiJkLmNoPqRsT123456
API Secret: secret_7uVwXyZ1234567890AbCdEfGhIj

Using API Keys

The Recommand Peppol API uses HTTP Basic Authentication. Your API key serves as the username and your API secret as the password.

HTTP Header Construction

For each request, include an Authorization header with the value Basic followed by the Base64-encoded string of your key and secret joined by a colon:

Authorization: Basic <Base64(API_KEY:API_SECRET)>

Examples

cURL

curl -X GET https://peppol.recommand.eu/api/peppol/{teamId}/companies \
  -u key_aBcDeFgHiJkLmNoPqRsT123456:secret_7uVwXyZ1234567890AbCdEfGhIj

Javascript (Node.js)

const fetch = require("node-fetch");

const API_KEY = "key_aBcDeFgHiJkLmNoPqRsT123456";
const API_SECRET = "secret_7uVwXyZ1234567890AbCdEfGhIj";

// Create Base64 encoded credentials
const credentials = Buffer.from(`${API_KEY}:${API_SECRET}`).toString("base64");

async function fetchCompanies(teamId) {
  const response = await fetch(
    `https://peppol.recommand.eu/api/peppol/${teamId}/companies`,
    {
      headers: {
        Authorization: `Basic ${credentials}`,
      },
    }
  );

  return response.json();
}

Python

import requests
import base64

API_KEY = 'key_aBcDeFgHiJkLmNoPqRsT123456'
API_SECRET = 'secret_7uVwXyZ1234567890AbCdEfGhIj'

# Create Base64 encoded credentials
credentials = base64.b64encode(f"{API_KEY}:{API_SECRET}".encode()).decode()

def fetch_companies(team_id):
    response = requests.get(
        f"https://peppol.recommand.eu/api/peppol/{team_id}/companies",
        headers={"Authorization": f"Basic {credentials}"}
    )

    return response.json()

PHP

<?php
$apiKey = 'key_aBcDeFgHiJkLmNoPqRsT123456';
$apiSecret = 'secret_7uVwXyZ1234567890AbCdEfGhIj';

// Create Base64 encoded credentials
$credentials = base64_encode($apiKey . ':' . $apiSecret);

$teamId = 'your_team_id';
$ch = curl_init("https://peppol.recommand.eu/api/peppol/{$teamId}/companies");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Basic {$credentials}"
]);

$response = curl_exec($ch);
$companies = json_decode($response, true);
curl_close($ch);
?>

Security Best Practices

1. Environment variables: Store keys as environment variables or in a secure vault.
2. Separate keys: Use different keys for development, testing, and production.
3. Rotate regularly: Generate new keys periodically and revoke old ones.

Troubleshooting

Authentication errors

If you receive a 401 Unauthorized response:

• Verify your API key and secret are correct
• Check if the key has been revoked
• Ensure the Base64 encoding is correct
• Make sure the team ID you are using is correct, all API keys are team-specific

Next Steps

• UBL Format Guide - Learn about the UBL document structure
• Sending Invoices - Learn how to create and send invoices
• API Authentication Reference - Complete details on authentication
• Troubleshooting Guide - Solve common authentication issues