Comment limiter une clé API à un seul projet

Une clé API peut être liée à un seul projet Cryptanio. Prenons un processus de rapprochement qui doit lire les factures d’une boutique en ligne sans accéder aux données des autres projets du compte. Il lui faut une clé distincte : le projet détermine le périmètre des données, tandis que les autorisations et les sections API définissent les opérations permises.

Ni le nom de la clé ni le numéro de projet dans votre application ne limitent l’accès à eux seuls. La restriction doit être enregistrée dans la politique de la clé. Cet accès concerne l’API publique v1 ; la clé n’est pas un mot de passe pour se connecter à l’espace de gestion.

1. Préparez le projet et les autorisations

Vous devez disposer des droits de propriétaire ou d’administrateur du compte et d’un projet actif existant avec le service « Paiements ». Vérifiez d’abord que son nom et son usage sont clairs : choisir le mauvais projet peut créer une clé valide, mais avec un périmètre inadapté.

Ouvrez « Clés API ». Dans le formulaire « Créer une clé API », renseignez « Étiquette », par exemple « Rapprochement boutique ». Un nom distinct permet d’identifier les processus serveur, mais la protection réelle se règle dans les champs suivants.

2. Choisissez le mode et un projet précis

Pour lire des factures réelles, choisissez « Production » dans « Mode ». La clé doit correspondre au mode des données demandées par votre serveur.

Dans « Projet », sélectionnez le projet voulu au lieu de « Tous les projets ». L’interface affiche une indication de restriction au service du projet sélectionné. La liaison au projet et l’accès au service s’appliquent ensemble : la clé n’active pas le service et n’étend pas ses possibilités à elle seule.

3. Conservez uniquement la lecture des factures

Dans « Accès », choisissez « Lecture seule ». Dans « Sections API », conservez « Factures » et décochez les autres cases si le processus n’en a pas besoin. Un rapprochement ordinaire des états de factures ne nécessite pas la gestion des adresses, des webhooks ou de la simulation.

Si un autre serveur doit créer des factures, il lui faut « Lire et écrire » et la section correspondante. Attribuez-lui une clé distincte au rôle clair, sans élargir inutilement les droits du processus de rapprochement. L’écriture s’applique aux sections sélectionnées, pas à toute l’API.

4. Configurez les IP et l’expiration

Dans « Adresses IP autorisées », indiquez les IP publiques de sortie du serveur ou les plages CIDR nécessaires, une par ligne. Il s’agit de l’adresse depuis laquelle la requête arrive à l’API, pas de l’IP de l’acheteur. Avec un hébergement ou un proxy, vérifiez l’adresse de sortie réelle.

Un champ vide autorise toute IP. Si le serveur utilise plusieurs adresses de sortie, prenez-les en compte ; sinon une clé valide peut échouer à la vérification. La restriction IP complète le choix du projet et des sections sans le remplacer.

Renseignez « Expire » si nécessaire. La date choisie reste valable jusqu’à la fin de la journée en UTC. Alignez-la sur la durée d’utilisation de l’intégration : une clé expirée ne signifie pas que le client n’a pas payé.

5. Créez la clé et conservez le secret

Cliquez sur « Créer une clé » et effectuez la confirmation de sécurité si elle est demandée. Copiez le secret affiché et conservez-le sur le serveur de rapprochement. Ne le placez pas dans le JavaScript côté client, un lien de paiement, les échanges avec l’acheteur ou un journal public.

Après la fermeture de la fenêtre, ne comptez pas retrouver le secret dans la liste : elle ne montre qu’une désignation abrégée de la clé. Vérifiez « Limite », le projet, les sections disponibles, l’expiration et le statut. Si un développeur a besoin d’un accès, transmettez-le via un stockage sécurisé approprié plutôt que de publier la clé avec les instructions.

6. Vérifiez les accès autorisés et refusés

Depuis un serveur dont l’IP est autorisée, lisez une facture connue de ce projet. Voici un exemple de lecture du catalogue API ; utilisez votre propre ID de facture et la clé créée :

#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_RESOURCE_ID:?Set CRYPTANIO_RESOURCE_ID}"
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
urlencode() {
  local LC_ALL=C text="$1" char index
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in [a-zA-Z0-9.~_-]) printf '%s' "$char" ;; *) printf '%%%02X' "'$char" ;; esac
  done
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request GET \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  "https://api.cryptanio.com/v1/invoices/$(urlencode "$CRYPTANIO_RESOURCE_ID")" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

Télécharger l’exemple

Vérifiez ensuite la limite avec une facture connue d’un autre de vos projets : ses données ne doivent pas être renvoyées. Les listes doivent aussi rester limitées au projet sélectionné. Cette clé ne peut pas créer ni modifier de factures, même si « Factures » est activé. La suite du rapprochement est expliquée dans le guide de vérification des paiements par API.

Si une requête échoue, vérifiez le projet, le mode, l’IP, l’expiration et les droits. Ne concluez pas à un impayé sur une seule erreur d’accès et ne remplacez pas la clé limitée par une clé de tout le compte. Le paiement s’évalue selon l’état de la facture.

Comment ajuster l’accès ensuite

Pour une clé existante, cliquez sur « Accès », modifiez le projet, les sections, les IP ou l’expiration, puis choisissez « Enregistrer l'accès ». Le mode se choisit à la création. « Renouveler » change le secret et désactive immédiatement l’ancien ; « Révoquer » arrête l’utilisation de la clé. Préparez la mise à jour des clients serveur avant ce remplacement pour ne pas interrompre le rapprochement des commandes.