Clé d’API
Comment fonctionne la clé bearer : un jeu de clés par client, avec des portées.
- Dans le bac à sable
En termes simples
La clé d’API permet à un système appelant de prouver qu’il est autorisé à utiliser le service. Chaque client a ses propres clés, et chaque clé a des portées qui disent ce qu’elle peut faire. Nous délivrons la première clé de bac à sable sur demande.
Envoyez la clé sous forme de jeton bearer à chaque appel.
Authorization: Bearer <your-api-key>Ce que le service en fait
Le service calcule l’empreinte SHA-256 de la clé que vous envoyez et la compare à celle qu’il détient. Il ne stocke aucune valeur de clé. Chaque utilisation écrit une ligne d’audit, qui ne contient pas non plus de valeur. Une clé de bac à sable commence par eik_test_, et une clé de production par eik_live_.
Une clé valide
Un appel qui nécessite une clé, avec une clé valide. La liste de suivi est vide, car rien n’a été rejeté.
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": []
}Une clé absente ou erronée
La réponse est 401, avant toute autre lecture.
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
}Clés et portées
Une clé appartient à un client et ne voit que les données de ce client. La facture d’un autre client reçoit 404.
| Portée | Ce que la clé peut faire |
|---|---|
submit | Envoyer des factures (POST /invoices, POST /invoices/xml), faire un essai à blanc (POST /validate) et annuler une facture. |
read | Lire les factures, les événements et les documents, la liste de suivi et le catalogue. |
admin | Gérer le webhook, les identifiants d’accès aux réseaux et les clés d’API du client. |
Un appel sans la portée dont il a besoin reçoit 403. Chaque portée a sa propre limite de débit.
Créer et révoquer des clés
Une clé n’est affichée qu’une fois, dans la réponse qui la crée. Nous n’en conservons que le SHA-256 : une clé perdue ne peut donc pas être réaffichée. Révoquez-la et créez-en une nouvelle.
- Une clé dotée de la portée
admincrée des clés pour son propre client, avec n’importe laquelle des portées qu’elle détient elle-même, et les révoque. Révoquer une clé révoque aussi toutes les clés qu’elle a créées. - Un client peut détenir jusqu’à 20 clés actives. Chaque appel est compté pour le client, et non pour la clé : davantage de clés n’achètent donc pas davantage de requêtes.
- Une clé révoquée cesse de fonctionner immédiatement.
La première clé d’un client vient de nous. Les clés suivantes sont créées par POST /keys.
Attention
Ne mettez pas de vraies clés dans les exemples, les tickets ou les e-mails.