A business API key authenticates machine calls as your business rather than as a person. You send it in the same api-key header you already use for personal keys — the only difference is the APIB- prefix. Every page you process with it is billed to the business subscription.
There is no separate authentication scheme to learn. Wherever a personal API-… key works, an APIB-… business key works too — the prefix is what makes the call business-scoped.
Both key types travel in the same api-key header, but they represent different actors and bill differently.
| Personal key | Business key | |
|---|---|---|
| Prefix | API-… |
APIB-… |
| Represents | Your personal account | The business (its service account) |
| Billed to | Your personal quota | The business subscription |
| Created by | You (self-serve) | A business OWNER or ADMIN |
| Sub-client header | Only if your account is wrapped | Yes (x-sub-business-id or x-sub-business-ref) |
Put the APIB-… key in the api-key header and call any endpoint exactly as before. Nothing else about the request changes — same URL, same multipart body, same response.
curl --location 'https://de.eagle-doc.com/api/receipt/v3/processing' \
--header 'api-key: APIB-your-business-key' \
--form 'file=@"receipt.jpeg"'import requests
resp = requests.post(
"https://de.eagle-doc.com/api/receipt/v3/processing",
headers={"api-key": "APIB-your-business-key"},
files={"file": open("receipt.jpeg", "rb")},
)
print(resp.json())import fs from "node:fs";
const form = new FormData();
form.append("file", new Blob([fs.readFileSync("receipt.jpeg")]), "receipt.jpeg");
const resp = await fetch("https://de.eagle-doc.com/api/receipt/v3/processing", {
method: "POST",
headers: { "api-key": "APIB-your-business-key" },
body: form,
});
console.log(await resp.json());Create, rename and revoke business API keys through the management API below, or from the dashboard. Rotate a key by creating a new one and revoking the old one.
The endpoints below live under /api/business/** and require a real-user token — your personal API-… key or a signed-in dashboard session — with the role ADMIN or OWNER. They reject APIB-… business keys (403, messageCode 3010). So create and rotate keys with your owner credentials or the dashboard, then use the resulting APIB-… key for the data plane.
List the businesses your account belongs to. Each item carries the id you need as {businessId} below, plus your role on that business in myRole.
| Name | Description |
|---|---|
| api-key (header) | A real-user token: your personal API- key or a signed-in dashboard session. APIB- business keys are rejected. |
| Code | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 |
An array of the businesses you are a member of.
|
||||||||||||
| 403 | An APIB- business key was used. messageCode 3010. |
Create a new business API key. Requires role ADMIN or OWNER. The response contains the full secret — this is the only place it is returned in a create call.
| Name | Description |
|---|---|
| api-key (header) | A real-user token with role ADMIN or OWNER. APIB- keys are rejected. |
| businessId (path) | The id from GET /api/business. |
| name (body, optional) | A label for the key. If blank, it defaults to "default". |
{
"name": "Production"
}| Code | Description |
|---|---|
| 201 |
The created BusinessApiKey, including the full secret in apiKey. The key format is APIB-<24hex>-<uuid>.
Store the secret securely
The full secret is returned here (and in the list endpoint). Treat it like a password and store it in your secrets manager — if it leaks, revoke it and create a new one. |
| 403 | An APIB- key was used (messageCode 3010) or your role is too low (messageCode 8003). |
List every API key on a business, including revoked ones. Requires role ADMIN or OWNER. A key with revokedAt set is inactive.
| Name | Description |
|---|---|
| api-key (header) | A real-user token with role ADMIN or OWNER. |
| businessId (path) | The id from GET /api/business. |
| Code | Description |
|---|---|
| 200 |
An array of BusinessApiKey objects, including revoked keys (revokedAt set = inactive).
|
Rename an existing key. Requires role ADMIN or OWNER. Only the label changes — the secret stays the same.
| Name | Description |
|---|---|
| api-key (header) | A real-user token with role ADMIN or OWNER. |
| businessId (path) | The id from GET /api/business. |
| keyId (path) | The id of the key to update. |
| name (body) | The new label for the key. |
{
"name": "New label"
}| Code | Description |
|---|---|
| 200 | The updated BusinessApiKey with the new name. |
Revoke a key. Requires role ADMIN or OWNER. Revocation is immediate and permanent; the key is kept for audit with revokedAt set.
| Name | Description |
|---|---|
| api-key (header) | A real-user token with role ADMIN or OWNER. |
| businessId (path) | The id from GET /api/business. |
| keyId (path) | The id of the key to revoke. |
| Code | Description |
|---|---|
| 200 | The key is revoked immediately (revokedAt set) and kept for audit. Calls that use it now fail. |
Do the same from the dashboard under Business → Settings → API keys. The secret is copy-once on creation, and you can revoke any key from there.
The management endpoints return the standard Eagle Doc error envelope. The most common authentication and authorization failures are:
| Status | messageCode | Meaning |
|---|---|---|
| 403 | 3010 API_KEY_NOT_AUTHORIZED |
You used an APIB- business key on a management endpoint. These endpoints require a real-user token (personal API- key or dashboard session). |
| 403 | 8003 BUSINESS_ROLE_INSUFFICIENT |
Your role on the business is too low. Creating, renaming and revoking keys requires ADMIN or OWNER. |
| 404 | 8000 BUSINESS_NOT_FOUND |
The business does not exist, or your account is not a member of it. |
Every error shares the same body shape, so you can parse messageCode the same way everywhere:
{
"httpCode": 403,
"httpCodeName": "FORBIDDEN",
"messageCode": 3010,
"message": "API key not permitted",
"messageDetails": [],
"data": null
}Building your multi-client integration and something is unclear? We are glad to help so your project succeeds.
Reach us at support@eagle-doc.com
Copyright © S2Tec GmbH