API Documentation

1. Simple - Client Credentials

Best choice when you are integrating the API directly into your own application and you act on behalf of yourself. There is no user-facing OAuth redirect - you exchange your API key for a short-lived bearer token and attach it to every request.

1. Open Settings / API Key in the application and copy your client_id and client_secret.
2. Request a token:

   POST /api/auth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=client_credentials
   &client_id=YOUR_CLIENT_ID
   &client_secret=YOUR_CLIENT_SECRET
   &scope=send_documents receive_documents

3. Use the returned access_token as a Bearer token in subsequent requests:

   Authorization: Bearer <access_token>

4. When the access token expires, use the refresh_token from the same response to obtain a new token pair without re-entering your credentials:

   POST /api/auth/renew
   Content-Type: application/json
   
   { "refresh_token": "YOUR_REFRESH_TOKEN" }

   Alternatively, simply request a brand-new token by repeating step 2 with your client_id and client_secret.

2. Simple OAuth - Authorization Code (own application)

Best choice when you are integrating into your own application but want to use the standard OAuth 2.0 Authorization Code flow. The user (you) will be redirected to a consent screen and asked to grant the requested permissions. This is useful when you want the token to be tied to an interactive session.

1. Open Settings / API Key and copy your client_id and client_secret. Set a redirect URI there.
2. Redirect the user to the authorization endpoint:

   GET /oauth/authorize
     ?response_type=code
     &client_id=YOUR_CLIENT_ID
     &redirect_uri=https://your-app.example.com/callback
     &scope=send_documents receive_documents
     &state=RANDOM_STATE

3. The user grants access. Exchange the returned code for a token:

   POST /api/auth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code
   &code=RETURNED_CODE
   &redirect_uri=https://your-app.example.com/callback
   &client_id=YOUR_CLIENT_ID
   &client_secret=YOUR_CLIENT_SECRET

3. Normal OAuth - Developer Application

Best choice when you are building a multi-tenant application that will be used by your own customers. Each customer logs in with their own account and explicitly grants your application access to their data. You act on their behalf using the token they issue.

1. Navigate to /developers/ and create a new Developer Application. You will receive a dedicated client_id and client_secret for that application.
2. Redirect your customer to the authorization endpoint (same as above), but using the Developer Application credentials and the scopes your application needs.

   GET /oauth/authorize
     ?response_type=code
     &client_id=YOUR_DEVELOPER_APP_CLIENT_ID
     &redirect_uri=https://your-app.example.com/callback
     &scope=send_documents
     &state=RANDOM_STATE

   If you already know which company you want to connect, pass one of the following to pre-select it on the consent screen - the user will see that participant highlighted/pre-filled:

   Parameter(s)	When to use	Example
   vatId	You know the company's EU VAT ID. Checked first; rn/countryCode are ignored when a match is found.	&vatId=CZ12345678
   rn + countryCode	You know the company's registration number and country. Both parameters are required together.	&rn=12345678&countryCode=CZ

   Matching is case-insensitive and whitespace-normalized. If no participant in the user's account matches, the consent screen shows all available participants and no pre-selection is applied.

3. The customer is shown a consent screen bound to their account and grants your application access.
4. Exchange the authorization code for a token. The issued token is scoped to the customer's account and the permissions they approved.

4. Affiliate ID - Lightweight Lookup Access

A simplified credential intended for read-only public lookups (e.g. checking whether a participant is registered in Peppol). The affiliateId is a UUID that can appear in URLs and referrer headers - it is treated as semi-public. Its main purpose is protection against anonymous abuse and DoS attacks, not strict authentication.

Pass it as a query parameter to lookup endpoints:

GET /api/lookup?affiliateId=YOUR_AFFILIATE_UUID&...

Permissions (Scopes)

When requesting a token you specify one or more scopes. The following scopes are available:

Request only the scopes your integration actually needs. Tokens issued via the Developer Application flow are further limited to the scopes the customer approved on the consent screen.