Authentication Guide

This guide explains how to authenticate with the Recommand Peppol API using our supported methods.

Authentication Methods

The Recommand Peppol API supports multiple authentication methods for different use cases.

API Key Authentication

Basic API Keys

Basic API keys use HTTP Basic Authentication. The API key ID is used as the username and the secret as the password.

Usage:

Authorization: Basic <base64(apiKeyId:secret)>

Creating a Basic API Key:

1. Navigate to the API Keys section in the dashboard
2. Create a new API key with type basic
3. Store the returned secret securely (it's only shown once)

Examples

Use the tabs to view your preferred language.

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

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

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

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

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

  return response.json();
}

import requests
import base64

API_KEY = 'key_aBcDeFgHiJkLmNoPqRsT123456'
API_SECRET = 'secret_7uVwXyZ1234567890AbCdEfGhIj'

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

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

    return response.json()

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

$credentials = base64_encode($apiKey . ':' . $apiSecret);

$ch = curl_init("https://app.recommand.eu/api/peppol/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);
?>

JWT API Keys

JWT API keys use Bearer token authentication. The JWT token is provided directly in the Authorization header.

Usage:

Authorization: Bearer <jwt-token>

Creating a JWT API Key:

1. Navigate to the API Keys section in the dashboard
2. Create a new API key with type jwt
3. Use the returned jwt token in your requests

Examples

Use the tabs to view your preferred language.

curl -X GET https://app.recommand.eu/api/peppol/companies \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

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

const JWT_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

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

  return response.json();
}

import requests

JWT_TOKEN = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

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

    return response.json()

<?php
$jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

$ch = curl_init("https://app.recommand.eu/api/peppol/companies");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$jwtToken}"
]);

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

OAuth2 with JWT Assertion

OAuth2 with JWT assertion allows you to authenticate using a client-signed JWT token. This method is suitable for server-to-server authentication where you control the private key used to sign the assertion.

Token Endpoint:

POST /api/core/oauth2/token

Request Parameters:

• grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion: A JWT token signed with your private key (RS256 algorithm)

Request Format:

Parameters MUST be sent in the HTTP request body as application/x-www-form-urlencoded with this header:

Content-Type: application/x-www-form-urlencoded

Response:

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id": "key_xxx"
}

Expiration of the access token is controlled by the expiration time of the JWT assertion.

Using the Access Token:

Use the returned access_token in subsequent API requests:

Authorization: Bearer <access_token>

JWT Assertion Requirements:

• Algorithm: RS256
• Claims:
  • iss: Your team ID
  • sub: Your team ID
  • team_id: Your team ID
  • user_id: Your user ID
  • exp: Expiration time (Unix timestamp)
  • aud: https://app.recommand.eu/api/core/oauth2/token

Example:

# Request access token (OAuth 2.0 JWT Bearer Grant)
curl -X POST "https://app.recommand.eu/api/core/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion=eyJhbGciOiJSUzI1NiJ9..."

# Use access token
curl -H "Authorization: Bearer <access_token>" https://app.recommand.eu/api/peppol/companies

Enabling OAuth2 with JWT Assertion

To enable OAuth2 with JWT assertion for your team, contact support and provide the following information. Keep in mind this feature is only available for enterprise customers on request.

• Team ID: Your team identifier (found in the API Keys section of the dashboard)
• JWKS (JSON Web Key Set): A JSON document containing your public key(s) in JWKS format. The public key(s) will be used to verify the JWT assertions you sign with your corresponding private key(s).

The JWKS should follow the RFC 7517 specification and contain at least one RSA public key (for RS256 algorithm). The JWKS MUST only contain the public portion of the RSA keys. Example JWKS structure:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "n": "base64url-encoded-modulus",
      "e": "base64url-encoded-exponent",
      "kid": "your-key-id"
    }
  ]
}

Once enabled, standard API key creation will be disabled for your team, and you'll be able to use OAuth2 with JWT assertion for authentication.

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
• For JWT or OAuth2, ensure your token is not expired
• Make sure the team ID you are using is correct, all API keys are team-specific

Next Steps