API-sleutel
Hoe de bearer-sleutel werkt: een eigen set sleutels per eindklant, met scopes.
- In de sandbox
In gewone woorden
Met de API-sleutel bewijst een aanroepend systeem dat het de dienst mag gebruiken. Elke eindklant heeft eigen sleutels, en elke sleutel heeft scopes die zeggen wat hij mag doen. Op aanvraag reiken we de eerste sleutel voor de sandbox uit.
Stuur de sleutel bij elke aanroep mee als bearer-token.
Authorization: Bearer <your-api-key>Wat de dienst ermee doet
De dienst hasht de sleutel die u stuurt met SHA-256 en vergelijkt die hash met de hash die hij bewaart. Hij slaat geen sleutelwaarde op. Elk gebruik schrijft een auditregel, en ook die regel bevat geen waarde. Een sleutel voor de sandbox begint met eik_test_, en een productiesleutel met eik_live_.
Een geldige sleutel
Een aanroep die een sleutel vereist, met een geldige sleutel. De opvolgingslijst is leeg omdat er niets is afgewezen.
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": []
}Een ontbrekende of verkeerde sleutel
Het antwoord is 401, voordat er iets anders wordt gelezen.
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
}Sleutels en scopes
Een sleutel hoort bij één eindklant en ziet alleen de gegevens van die eindklant. De factuur van een andere eindklant geeft 404.
| Scope | Wat de sleutel mag doen |
|---|---|
submit | Facturen verzenden (POST /invoices, POST /invoices/xml), een proefrun uitvoeren (POST /validate) en een factuur annuleren. |
read | Facturen, statusberichten en documenten lezen, de opvolgingslijst en de catalogus. |
admin | De webhook, de toegangsgegevens voor netwerken en de API-sleutels van de eindklant beheren. |
Een aanroep zonder de scope die hij nodig heeft, geeft 403. Elke scope heeft een eigen limiet.
Sleutels aanmaken en intrekken
Een sleutel wordt één keer getoond, in het antwoord dat hem aanmaakt. Wij bewaren alleen de SHA-256 ervan, dus een verloren sleutel kan niet opnieuw worden getoond: trek hem in en maak een nieuwe aan.
- Een sleutel met de scope
adminmaakt sleutels aan voor de eigen eindklant, met alle scopes die hij zelf heeft, en trekt ze in. Het intrekken van een sleutel trekt ook elke sleutel in die hij heeft aangemaakt. - Eén eindklant kan maximaal 20 actieve sleutels hebben. Elke aanroep wordt voor de eindklant geteld, niet voor de sleutel, dus meer sleutels leveren niet meer aanvragen op.
- Een ingetrokken sleutel werkt meteen niet meer.
De eerste sleutel voor een eindklant komt van ons. Latere sleutels worden aangemaakt met POST /keys.
Waarschuwing
Gebruik geen echte sleutels in voorbeelden, tickets of e-mails.