Authentification

Chaque requête API transmet un jeton d'accès dans l'en-tête Authorization. Vous obtenez ce jeton en échangeant une clé API, composée d'un Client ID et d'un Client secret, auprès du point de terminaison de jeton.

Créer une clé API

Les clés API sont créées dans l'application DocPayload sous Dashboard > Settings > API access > Manage keys > Generate Key.

Une clé est une paire :

Partie	Exemple	Remarques
Client ID	b0aa7303e6704e2188b42681d7b353fe	32 caractères hexadécimaux
Client secret	une longue chaîne aléatoire	Affiché une seule fois, à la génération de la clé. Copiez-le à ce moment : il ne sera plus affiché

Une clé expire au bout d'environ six mois ; la boîte de dialogue indique sa date d'expiration. La même boîte de dialogue affiche votre Tenant ID, que chaque point de terminaison prend dans son chemin.

Échanger la clé contre un jeton d'accès

Envoyez le Client ID et le secret au point de terminaison de jeton :

curl -X POST https://api.docpayload.com/v1/api-auth/token \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET" }'

Succès (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "document:read document:write metrics:read asset:upload document:delete"
}

Des identifiants incorrects reçoivent 401 Unauthorized.

Utiliser le jeton d'accès

Tous les autres appels, y compris le téléchargement d'un document généré, transmettent le jeton comme jeton Bearer :

Authorization: Bearer YOUR_ACCESS_TOKEN

Le jeton est valable 3600 secondes (expires_in). Conservez-le et réutilisez-le pour chaque appel jusqu'à son expiration, puis demandez-en un nouveau ; ne demandez pas un jeton par appel.

Liste d'adresses IP autorisées

La boîte de dialogue API access contient aussi une liste facultative d'adresses IP autorisées. Lorsqu'elle est renseignée, seules les adresses listées peuvent utiliser vos clés.

Bonnes pratiques de sécurité

• Stockez le Client ID et le secret dans des variables d'environnement ou un coffre de secrets, jamais dans le code source
• Renouvelez une clé en en générant une nouvelle, en y basculant votre intégration, puis en révoquant l'ancienne
• Renseignez la liste d'adresses IP autorisées avec les adresses depuis lesquelles vos serveurs appellent l'API
• Gardez le jeton d'accès côté serveur ; n'envoyez jamais le secret ni le jeton à un navigateur

Réponses d'erreur

État	Description
401 Unauthorized	Jeton d'accès manquant, invalide ou expiré, ou Client ID ou secret incorrect
403 Forbidden	Le jeton n'a pas de permission pour cette ressource, ou l'URL désigne un autre tenant
429 Too Many Requests	Limite de débit dépassée