Ein Business-API-Schlüssel authentifiziert maschinelle Aufrufe als Ihr Business und nicht als Person. Sie senden ihn im selben api-key-Header, den Sie bereits für persönliche Schlüssel verwenden — der einzige Unterschied ist das Präfix APIB-. Jede damit verarbeitete Seite wird dem Business-Abonnement in Rechnung gestellt.
Es gibt kein separates Authentifizierungsverfahren zu lernen. Überall dort, wo ein persönlicher API-…-Schlüssel funktioniert, funktioniert auch ein APIB-…-Business-API-Schlüssel — das Präfix macht die Anfrage business-bezogen.
Beide Schlüsseltypen werden im selben api-key-Header gesendet, aber sie stehen für unterschiedliche Akteure und werden unterschiedlich abgerechnet.
| Persönlicher Schlüssel | Business-Schlüssel | |
|---|---|---|
| Präfix | API-… |
APIB-… |
| Steht für | Ihr persönliches Konto | Das Business (dessen Service-Account) |
| Abgerechnet über | Ihr persönliches Kontingent | Das Business-Abonnement |
| Erstellt von | Sie selbst (Self-Service) | Ein OWNER oder ADMIN des Business |
| Sub-Kunden-Header | Nur wenn Ihr Konto umschlossen ist | Ja (x-sub-business-id oder x-sub-business-ref) |
Setzen Sie den APIB-…-Schlüssel in den api-key-Header und rufen Sie jeden Endpunkt genau wie zuvor auf. Sonst ändert sich an der Anfrage nichts — gleiche URL, gleicher Multipart-Body, gleiche Antwort.
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());Erstellen, benennen und widerrufen Sie Business-API-Schlüssel über die untenstehende Verwaltungs-API oder im Dashboard. Rotieren Sie einen Schlüssel, indem Sie einen neuen erstellen und den alten widerrufen.
Die untenstehenden Endpunkte liegen unter /api/business/** und erfordern ein echtes Benutzer-Token — Ihren persönlichen API-…-Schlüssel oder eine angemeldete Dashboard-Sitzung — mit der Rolle ADMIN oder OWNER. Sie weisen APIB-…-Business-API-Schlüssel ab (403, messageCode 3010). Erstellen und rotieren Sie Schlüssel daher mit Ihren Owner-Zugangsdaten oder dem Dashboard und verwenden Sie den daraus resultierenden APIB-…-Schlüssel für die Datenebene.
Listet die Businesses auf, denen Ihr Konto angehört. Jeder Eintrag enthält die id, die Sie unten als {businessId} benötigen, sowie Ihre Rolle in diesem 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. |
Erstellt einen neuen Business-API-Schlüssel. Erfordert die Rolle ADMIN oder OWNER. Die Antwort enthält das vollständige Geheimnis — dies ist die einzige Stelle, an der es bei einem Erstellungsaufruf zurückgegeben wird.
| 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>.
Das Geheimnis sicher aufbewahren
Das vollständige Geheimnis wird hier (und im Listen-Endpunkt) zurückgegeben. Behandeln Sie es wie ein Passwort und speichern Sie es in Ihrem Secrets-Manager — falls es durchsickert, widerrufen Sie es und erstellen Sie ein neues. |
| 403 | An APIB- key was used (messageCode 3010) or your role is too low (messageCode 8003). |
Listet jeden API-Schlüssel eines Business auf, einschließlich widerrufener. Erfordert die Rolle ADMIN oder OWNER. Ein Schlüssel mit gesetztem revokedAt ist inaktiv.
| 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).
|
Benennt einen bestehenden Schlüssel um. Erfordert die Rolle ADMIN oder OWNER. Nur die Bezeichnung ändert sich — das Geheimnis bleibt gleich.
| 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. |
Widerruft einen Schlüssel. Erfordert die Rolle ADMIN oder OWNER. Der Widerruf erfolgt sofort und ist endgültig; der Schlüssel wird mit gesetztem revokedAt zu Prüfzwecken aufbewahrt.
| 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. |
Dasselbe geht im Dashboard unter Business → Einstellungen → API-Schlüssel. Das Geheimnis lässt sich bei der Erstellung nur einmal kopieren, und Sie können dort jeden Schlüssel widerrufen.
Die Verwaltungs-Endpunkte geben die Standard-Fehlerhülle von Eagle Doc zurück. Die häufigsten Authentifizierungs- und Autorisierungsfehler sind:
| Status | messageCode | Bedeutung |
|---|---|---|
| 403 | 3010 API_KEY_NOT_AUTHORIZED |
Sie haben einen APIB--Business-API-Schlüssel an einem Verwaltungs-Endpunkt verwendet. Diese Endpunkte erfordern ein echtes Benutzer-Token (persönlicher API--Schlüssel oder Dashboard-Sitzung). |
| 403 | 8003 BUSINESS_ROLE_INSUFFICIENT |
Ihre Rolle im Business ist zu niedrig. Das Erstellen, Umbenennen und Widerrufen von Schlüsseln erfordert ADMIN oder OWNER. |
| 404 | 8000 BUSINESS_NOT_FOUND |
Das Business existiert nicht, oder Ihr Konto ist kein Mitglied davon. |
Jeder Fehler hat dieselbe Body-Struktur, sodass Sie messageCode überall gleich auswerten können:
{
"httpCode": 403,
"httpCodeName": "FORBIDDEN",
"messageCode": 3010,
"message": "API key not permitted",
"messageDetails": [],
"data": null
}Sie bauen Ihre Integration für mehrere Kunden auf und etwas ist unklar? Wir helfen Ihnen gerne, damit Ihr Projekt gelingt.
Erreichen Sie uns unter support@eagle-doc.com
Copyright © S2Tec GmbH