Authentification

Chaque requête est authentifiée avec une seule clé API. Vous l’envoyez comme en-tête X-API-Key — pas de valse OAuth, pas d’échange de jetons.

Portée d’une clé API

Une clé API donne accès uniquement au service de téléversement de PDF — les endpoints /api/v1/upload-service/* (téléverser, statut de la tâche, télécharger, supprimer). C’est toute la surface de traitement publique.

Créer une clé API

La manière habituelle d’obtenir une clé est le portail Accessful : connectez-vous, ouvrez Clés API et créez-en une. La clé n’est affichée qu’une seule fois à la création — copiez-la immédiatement. Nous n’en stockons qu’un hachage, nous ne pourrons donc jamais la réafficher.

Une clé ressemble à ceci :

ak_oCe4cm015zL8vCbBne_wUZDcM6G1RWqD7Ekc2944EAA

• Préfixe ak_ suivi de 43 caractères compatibles avec les URL.
• Vous pouvez détenir jusqu’à 10 clés actives par compte.
• Une clé peut éventuellement porter une date d’expiration ; révoquez-la à tout moment depuis le portail.

Attention

Traitez la clé comme un mot de passe. Elle est liée à votre compte et peut téléverser, télécharger et supprimer définitivement vos cas. Ne l’intégrez jamais dans du code client que vous distribuez aux utilisateurs finaux.

Gérer les clés par programmation (facultatif)

Si vous automatisez la rotation des clés, les endpoints de gestion se trouvent sous /api/v1/auth/api-keys et nécessitent un jeton bearer OAuth2 issu de votre connexion au portail (Authorization: Bearer <jwt>) — pas une clé API :

Méthode & chemin	Objet
POST /api/v1/auth/api-keys	Créer une clé — la réponse contient le texte en clair une seule fois
GET /api/v1/auth/api-keys	Lister vos clés (valeurs masquées)
POST /api/v1/auth/api-keys/{id}/revoke	Révoquer une clé
DELETE /api/v1/auth/api-keys/{id}	Supprimer une clé

Envoyer la clé sur les requêtes

Ajoutez l’en-tête X-API-Key à chaque appel :

curl

curl https://api.accessful.de/api/v1/upload-service/job-status/<caseId> \
  -H "X-API-Key: ak_votre_cle_ici"

Node.js

await fetch(`https://api.accessful.de/api/v1/upload-service/job-status/${caseId}`, {
  headers: { 'X-API-Key': process.env.ACCESSFUL_API_KEY },
});

Java

HttpRequest.newBuilder()
    .uri(URI.create("https://api.accessful.de/api/v1/upload-service/job-status/" + caseId))
    .header("X-API-Key", System.getenv("ACCESSFUL_API_KEY"))
    .GET().build();

Vérifier votre clé

Faites un test rapide en demandant un cas aléatoire et inexistant. Une clé qui fonctionne renvoie 404 (le cas n’existe pas) — et non 401.

1. Envoyez une requête de statut avec un ID de cas jetable :

   curl -i https://api.accessful.de/api/v1/upload-service/job-status/00000000-0000-0000-0000-000000000000 \
     -H "X-API-Key: ak_votre_cle_ici"

2. Lisez la ligne de statut :

   • 404 Not Found → votre clé est acceptée. ✅
   • 401 Unauthorized → la clé est manquante, mal formée ou révoquée.

Erreurs d’authentification

Statut	Signification
401 Unauthorized	Pas de clé, clé mal formée ou clé révoquée/expirée.
403 Forbidden	La clé est valide mais n’a pas la permission pour cette action.

Une clé manquante ou non valide (401) est rejetée au niveau du gateway, avant que la requête n’atteigne l’application — un 401 ne porte donc jamais de corps Problem Details. Fiez-vous au code de statut. Un 403 provient de l’application elle-même et porte un corps Problem Details, comme les autres erreurs applicatives.