Authentication
The API uses the OAuth2 client credentials flow. You exchange a client id and secret for a
short-lived Bearer token at POST /v1/oauth/token, and send the token on every other call:
Authorization: Bearer <accessToken>
The token request
The token route accepts the standard OAuth2 form (application/x-www-form-urlencoded) and JSON.
Form:
grant_type=client_credentials&client_id=<client id>&client_secret=<client secret>
JSON:
{ "clientId": "<client id>", "clientSecret": "<client secret>" }
The answer:
{
"accessToken": "eyJhbGciOi...",
"tokenType": "Bearer",
"expiresIn": 3600,
"scope": "codes:issue codes:read",
"environment": "sandbox"
}
expiresInis the lifetime in seconds. Cache the token and reuse it; request a new one shortly before it expires, or when a call answers 401invalid_token.scopeis a space-separated list of the scopes the token grants.environmentis the client's environment,sandboxorproduction.- The token route is limited to 30 requests per minute per IP address. Fetching a new token for every call will hit that limit.
Examples
curl
TOKEN=$(curl -s https://api-sandbox.b2bgroup.dk/v1/oauth/token \
-d grant_type=client_credentials \
-d client_id="$CLIENT_ID" \
-d client_secret="$CLIENT_SECRET" | jq -r .accessToken)
curl -s https://api-sandbox.b2bgroup.dk/v1/codes/ABC-7K3Q-M8ZP/status \
-H "Authorization: Bearer $TOKEN"
C#
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.b2bgroup.dk") };
var tokenResponse = await http.PostAsync("/v1/oauth/token", new FormUrlEncodedContent(new Dictionary<string, string>
{
["grant_type"] = "client_credentials",
["client_id"] = clientId,
["client_secret"] = clientSecret,
}));
tokenResponse.EnsureSuccessStatusCode();
var token = await tokenResponse.Content.ReadFromJsonAsync<TokenResponse>();
// Every later call in these guides uses this HttpClient.
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token!.AccessToken);
var status = await http.GetFromJsonAsync<JsonElement>("/v1/codes/ABC-7K3Q-M8ZP/status");
public record TokenResponse(string AccessToken, string TokenType, int ExpiresIn, string Scope, string Environment);
Node
Node 18 or later (built-in fetch).
const baseUrl = 'https://api-sandbox.b2bgroup.dk';
const tokenResponse = await fetch(`${baseUrl}/v1/oauth/token`, {
method: 'POST',
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.CLIENT_ID,
client_secret: process.env.CLIENT_SECRET,
}),
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { accessToken } = await tokenResponse.json();
// Every later call in these guides sends these headers.
const headers = { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' };
const status = await (await fetch(`${baseUrl}/v1/codes/ABC-7K3Q-M8ZP/status`, { headers })).json();
Python
Uses the requests package.
import os
import requests
BASE_URL = "https://api-sandbox.b2bgroup.dk"
token_response = requests.post(f"{BASE_URL}/v1/oauth/token", data={
"grant_type": "client_credentials",
"client_id": os.environ["CLIENT_ID"],
"client_secret": os.environ["CLIENT_SECRET"],
})
token_response.raise_for_status()
access_token = token_response.json()["accessToken"]
# Every later call in these guides uses this session.
session = requests.Session()
session.headers["Authorization"] = f"Bearer {access_token}"
status = session.get(f"{BASE_URL}/v1/codes/ABC-7K3Q-M8ZP/status").json()
When the token request fails
| Status | error | Meaning |
|---|---|---|
| 400 | validation_error | The body could not be read, or the form did not say grant_type=client_credentials. |
| 401 | invalid_client | The client id or secret is missing or wrong, the client is inactive, or the client belongs to the other environment. The message then names the host to use, for example This client belongs to the sandbox environment; use https://api-sandbox.b2bgroup.dk. |
| 403 | ip_not_allowed | The credentials are correct, but the request does not come from an address on the client's IP allowlist. See IP allowlist. |
| 403 | certificate_required | The credentials are correct, but the client has client certificates registered and the request did not present one. See Client certificates (mTLS). |
| 403 | certificate_not_allowed | The credentials are correct, but the client certificate presented is not registered for the client. See Client certificates (mTLS). |
| 429 | rate_limited | More than 30 token requests per minute from your IP address. Wait the number of seconds in Retry-After. |
When a call with a token fails
| Status | error | Meaning |
|---|---|---|
| 401 | invalid_token | The token is missing, expired or invalid, or it was issued for the other environment. Get a new token. |
| 403 | insufficient_scope | The token does not grant the scope the operation requires. Add the scope to the client in the developer portal and get a new token. |
| 403 | ip_not_allowed | The call comes from an address outside the client's IP allowlist. The allowlist is checked on every call, not only when the token is issued. The list travels inside the token, so a change to the allowlist takes effect from the next token you request. |
| 403 | certificate_required | The client has client certificates registered, and the call did not present one. Checked on every call, like the IP allowlist, and the list travels inside the token in the same way. See Client certificates (mTLS). |
| 403 | certificate_not_allowed | The call presented a client certificate that is not registered for the client. See Client certificates (mTLS). |
Rotating the client secret
A client can have two active secrets at the same time. Create a new secret in the developer portal,
deploy it to your systems, and the previous secret keeps working for a grace period (7 days unless you
choose otherwise, between 1 and 30 days). When the grace period ends, the previous secret can no
longer get new tokens, but a token it already got keeps working until that token expires. You can
also revoke a secret immediately. Revoking stops the secret from getting new tokens at once; an access
token already issued with it is not revoked and keeps working until it expires (tokens are valid for
60 minutes, expiresIn 3600). Secrets are shown once and stored by us only as a hash.