API-Schlüssel
Wie der Bearer-Schlüssel funktioniert: ein Satz Schlüssel je Kunde, mit Scopes.
- In der Sandbox
In einfachen Worten
Mit dem API-Schlüssel weist ein aufrufendes System nach, dass es den Service nutzen darf. Jeder Kunde hat eigene Schlüssel, und jeder Schlüssel hat Scopes, die sagen, was er darf. Den ersten Sandbox-Schlüssel stellen wir auf Anfrage aus.
Senden Sie den Schlüssel bei jedem Aufruf als Bearer-Token.
Authorization: Bearer <your-api-key>Was der Service damit macht
Der Service bildet aus dem gesendeten Schlüssel einen SHA-256-Hash und vergleicht ihn mit dem Hash, den er vorhält. Er speichert keinen Schlüsselwert. Jede Nutzung schreibt eine Zeile ins Audit-Log, und auch diese Zeile enthält keinen Wert. Ein Sandbox-Schlüssel beginnt mit eik_test_, ein Produktivschlüssel mit eik_live_.
Ein gültiger Schlüssel
Ein Aufruf, der einen Schlüssel braucht, mit einem gültigen Schlüssel. Die Betreuungsliste ist leer, weil nichts abgelehnt wurde.
curl "https://api-sandbox-eu.eurinvoice.com/care" \
-H "Authorization: Bearer <your-api-key>"import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/care"))
.header("Authorization", "Bearer <your-api-key>")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}const response = await fetch('https://api-sandbox-eu.eurinvoice.com/care', {
headers: {
Authorization: 'Bearer <your-api-key>',
},
});
console.log(response.status);
console.log(await response.text());{
"data": []
}Ein fehlender oder falscher Schlüssel
Die Antwort ist 401, bevor irgendetwas anderes gelesen wird.
curl "https://api-sandbox-eu.eurinvoice.com/invoices/inv_unknown"import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/invoices/inv_unknown"))
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}const response = await fetch('https://api-sandbox-eu.eurinvoice.com/invoices/inv_unknown', {
});
console.log(response.status);
console.log(await response.text());{
"type": "https://eurinvoice.com/problems/unauthorized",
"title": "Missing or unknown API key",
"status": 401
}Schlüssel und Scopes
Ein Schlüssel gehört zu einem Kunden und sieht nur dessen Daten. Für die Rechnung eines anderen Kunden lautet die Antwort 404.
| Scope | Was der Schlüssel darf |
|---|---|
submit | Rechnungen senden (POST /invoices, POST /invoices/xml), einen Probelauf ausführen (POST /validate) und eine Rechnung stornieren. |
read | Rechnungen, Ereignisse und Dokumente, die Betreuungsliste und den Katalog lesen. |
admin | Den Webhook, die Zugangsdaten für die Netze und die API-Schlüssel des Kunden verwalten. |
Auf einen Aufruf ohne den nötigen Scope lautet die Antwort 403. Jeder Scope hat sein eigenes Ratenlimit.
Schlüssel erstellen und widerrufen
Ein Schlüssel wird einmal angezeigt, in der Antwort, die ihn erstellt. Wir behalten nur seinen SHA-256-Hash, ein verlorener Schlüssel kann also nicht erneut angezeigt werden: Widerrufen Sie ihn und erstellen Sie einen neuen.
- Ein Schlüssel mit dem Scope
adminerstellt Schlüssel für den eigenen Kunden, mit beliebigen Scopes, die er selbst hat, und widerruft sie. Wer einen Schlüssel widerruft, widerruft auch jeden Schlüssel, den dieser erstellt hat. - Ein Kunde darf bis zu 20 gültige Schlüssel halten. Jeder Aufruf wird für den Kunden gezählt, nicht für den Schlüssel, mehr Schlüssel bringen also nicht mehr Anfragen.
- Ein widerrufener Schlüssel funktioniert sofort nicht mehr.
Den ersten Schlüssel für einen Kunden erhält man von uns. Weitere Schlüssel werden über POST /keys erstellt.
Warnung
Halten Sie echte Schlüssel aus Beispielen, Tickets und E-Mails heraus.