Authentication

Manage API keys, switch between environments, and understand rate limits.

API Keys

Create and manage API keys from the getpeppr console. Keys are scoped by environment — sandbox keys can only access the test network, and production keys are for live Peppol delivery.

Environments

  • sk_sandbox_... — sandbox mode, no real invoices sent
  • sk_live_... — production mode, live Peppol network

The gateway resolves the environment from the key itself — the SDK has no environment switch to set.

API keys are shown only once at creation time. Store them securely in environment variables — if you lose a key, revoke it and create a new one.
Use separate keys for different services or environments. If a key is compromised, you can revoke it without affecting your other integrations.
Using the CLI? Run getpeppr login to store your key in $XDG_CONFIG_HOME/getpeppr/credentials.json (~/.config by default, %APPDATA% on Windows; on Unix-like systems the file is created and checked with mode 0600) — the CLI picks the right one automatically. See the CLI docs. 
import { Peppol } from "@getpeppr/sdk";

// Sandbox key — for testing (no real invoices sent)
const sandbox = new Peppol({
  apiKey: "sk_sandbox_abc123...",
});

// Production key — live Peppol network
const production = new Peppol({
  apiKey: "sk_live_xyz789...",
});

// The gateway resolves the environment from the key — the SDK has no
// environment switch:
//   sk_sandbox_... → sandbox (test network)
//   sk_live_...    → production

Rate Limits

Limits

  • 5 active standard keys per environment per account, plus 1 master key per environment on a Platform account
  • 10 key creations per hour per account
  • API request limits vary by plan (10–300 req/min per key, 50–1,500 req/min per account)
  • Validation request limits use a separate per-key bucket (20–600 req/min depending on plan)

If you reach the standard-key limit, revoke an existing key from the console to create a new one. The per-account rate limit applies across all your keys combined. Validation endpoints have their own per-key bucket so pre-flight checks do not consume the send/list per-key quota. See Sandbox for the full comparison table.

If you are on a Platform contract, your account carries the top of those ranges — 300 req/min per key and 1,500 per account — from the moment the contract is live, on both your sandbox and your production keys. Your console may still show the account as Sandbox: that label tracks the standard self-serve plans, not your contract.

Enrolling customer companies has its own, tighter limits that these ranges do not cover: 60 company creations per minute per account, and 20 attestation emails per hour per account. The attestation step is required before a production company can be published to the network, so a bulk migration is paced by that hourly limit rather than by the per-minute budget above. Plan a large migration with us rather than against the clock.

Rate Limit Response

When you exceed rate limits, the API returns a 429 Too Many Requests response. How long to wait is in the standard Retry-After response header, in seconds — the body carries the message only.

The SDK automatically handles rate limiting with exponential backoff. Manual retry logic is only needed for direct API calls.
429 Response
{
  "error": "Rate limit exceeded. Try again later."
}
Onboarding Setup
Sandbox