Gouvernance des API de production sur AceDataCloud

Une clé API de production n’est pas seulement une chaîne secrète. C’est un point de contrôle pour déterminer qui peut appeler quoi, combien ils peuvent consommer, combien de temps l’accès dure, quelle Application paie et comment un incident peut être tracé.

AceDataCloud expose ces contrôles sur quatre couches connectées :

Émission des identifiants — créer une clé pour une Application spécifique.
Politique de solde de l’Application — déterminer où l’utilisation est déduite et ce qui se produit lorsque le quota est faible.
Observabilité de l’utilisation — tracer le statut, le coût, la latence, l’API, l’Application et l’identifiant.
Cycle de vie des identifiants — mettre à jour les restrictions, faire tourner les secrets et révoquer l’accès.

Boucle de contrôle de la gouvernance des API de production

Ce guide transforme les API de gestion individuelles de la plateforme en un modèle opérationnel pratique.

¶ D’abord, séparez les deux types d’identifiants

AceDataCloud utilise différents identifiants pour différentes surfaces :

Identifiant	Utilisé pour	Hôte typique
Jeton de compte / Jeton de plateforme	Gestion de compte : Applications, identifiants, soldes, utilisation, commandes	`platform.acedata.cloud/api/v1/**`
Identifiant API	Appeler les API métier pour un service	`api.acedata.cloud/**`

Ils ne sont pas interchangeables. Un identifiant d’API métier ne doit pas être utilisé pour appeler des points de terminaison de gestion, et un Jeton de plateforme ne doit pas être intégré dans une application comme clé API métier.

Cette séparation crée une limite de sécurité utile :

Conservez les Jetons de plateforme dans un environnement opérationnel étroitement contrôlé.
Donnez à chaque charge de travail son propre Identifiant API.
Laissez les services d’exécution appeler uniquement les API métier dont ils ont besoin.
Laissez CI ou un service administratif effectuer la gestion des identifiants et des soldes.

¶ Émettez un identifiant par charge de travail et environnement

Créez un identifiant avec POST https://platform.acedata.cloud/api/v1/credentials/ en utilisant un Jeton de compte.

Une requête minimale orientée production peut inclure un nom d’affichage, une limite de consommation indépendante, une expiration et une liste d’autorisation d’API :

curl -X POST 'https://platform.acedata.cloud/api/v1/credentials/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"application_id\": \"${APPLICATION_ID}\",
    \"name\": \"prod-support-agent\",
    \"limited_amount\": 100,
    \"expired_at\": \"2027-01-01T00:00:00Z\",
    \"allowed_api_ids\": [\"${CHAT_API_ID}\"],
    \"metadata\": {\"environment\": \"production\", \"owner\": \"support-platform\"}
  }"

Le contrat de création prend en charge :

Champ	Objectif de gouvernance
`application_id`	Lie l’utilisation à l’Application cible
`name`	Rend la charge de travail identifiable lors des audits
`limited_amount`	Définit une limite d’utilisation indépendante pour l’identifiant ; `null` signifie aucune limite indépendante
`expired_at`	Établit un accès automatique limité dans le temps
`allowed_api_ids`	Restreint l’identifiant aux API sélectionnées
`host`	Stocke les informations d’hôte de l’identifiant lorsque cela est applicable
`for_user_id`	Permet à un propriétaire d’Application d’émettre des identifiants délégués pour un autre utilisateur
`tags` / `metadata`	Enregistre le contexte de l’environnement, de l’équipe, du système ou du ticket de modification

Un tableau allowed_api_ids vide est normalisé comme aucune restriction. N’envoyez pas un tableau vide lorsque votre intention est « ne rien autoriser ». Utilisez une véritable liste d’autorisation d’API.

Les services API/Agent renvoient normalement un identifiant Token. Les services Proxy renvoient normalement une identité nom d’utilisateur/mot de passe, et une Application Proxy n’autorise qu’un seul identifiant.

Traitez la réponse de création comme sensible. Enregistrez immédiatement le secret dans un gestionnaire de mots de passe ou un gestionnaire de secrets et n’écrivez pas la réponse dans les journaux. Les clients ne doivent pas dépendre de la possibilité de récupérer ultérieurement des secrets en texte brut ; les API de cycle de vie peuvent renvoyer des valeurs masquées.

¶ Utilisez les limites comme contrôles du rayon d’impact, et pas seulement pour la budgétisation

Un limited_amount au niveau de l’identifiant est utile pour contenir une clé divulguée ou une charge de travail incontrôlée, mais ce n’est qu’une partie de la gouvernance des coûts.

Une hiérarchie robuste est :

Limite d’identifiant : exposition maximale pour une charge de travail.
Solde de l’Application : quota disponible pour l’Application de service souscrite.
Politique de solde global : solution de secours facultative pour les Applications éligibles au paiement à l’utilisation.
Autorisation de découvert : une autorisation de plateforme distincte, en lecture seule, que les clients ne peuvent pas activer eux-mêmes.

Ne les traitez pas comme équivalentes.

Par exemple, même lorsqu’une Application dispose d’un quota disponible, une limite d’identifiant individuelle peut toujours bloquer la charge de travail. À l’inverse, l’activation du partage du solde global peut permettre à une Application éligible de continuer après que son propre solde est devenu insuffisant — mais cela ne supprime pas les limites d’identifiant, la désactivation ou les contrôles d’expiration.

¶ Surveillez le solde avec l’unité et le statut

Interrogez une Application avec :

curl --fail-with-body \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

Les champs qui comptent sur le plan opérationnel incluent :

remaining_amount — quota actuel de l’Application ; une valeur négative indique un quota en attente de règlement.
used_amount — utilisation cumulée signalée pour l’Application.
service.unit — l’unité, telle que Credit, Count ou Token.
disabled — indique si l’Application est désactivée.
expired_at — indique si l’accès par abonnement a expiré.
allow_overdraft — indication en lecture seule d’un découvert approuvé par l’administrateur.

Ne supposez jamais que le montant est en dollars américains. Les seuils d’alerte doivent être définis dans l’unité réelle du service.

Un solde positif seul ne prouve pas la disponibilité. Votre contrôle de santé doit évaluer le solde, disabled, l’expiration, les limites d’identifiant et le statut du service. Pour les services Proxy, la synchronisation du solde peut être suspendue ou expirer, auquel cas le solde enregistré le plus récemment peut être renvoyé.

Une vérification Python concise :

import os
import requests

minimum = float(os.getenv("MINIMUM_BALANCE", "10"))
url = f"https://platform.acedata.cloud/api/v1/applications/{os.environ['APPLICATION_ID']}"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}

response = requests.get(url, headers=headers, timeout=10)
response.raise_for_status()
application = response.json()

remaining = application.get("remaining_amount")
unit = application.get("service", {}).get("unit", "unknown")

if application.get("disabled"):
    raise RuntimeError("Application is disabled")
if application.get("expired_at"):
    print("Check whether the Application expiry has passed:", application["expired_at"])
if remaining is None:
    raise RuntimeError("No balance is available for this Application")
if not application.get("allow_overdraft", False) and float(remaining) < minimum:
    raise RuntimeError(f"Low balance: {remaining} {unit}")

Pour plusieurs services, récupérez une fois la liste des Applications et évaluez chaque élément localement au lieu d’interroger chaque point de terminaison de détail d’Application à haute fréquence.

¶ Décidez explicitement si le partage du solde global est autorisé

Les Applications éligibles au paiement à l’utilisation peuvent être configurées pour utiliser le solde global du compte lorsque leur propre solde est insuffisant :

curl -X POST \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}/update-allow-consume-global/" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"allow_consume_global": true}'

Utilisez la valeur allow_consume_global renvoyée comme source de vérité. Ne supposez pas que la valeur demandée a été enregistrée.

Contraintes importantes :

Les Applications Period ne peuvent pas consommer le solde global ; le serveur conserve le champ à false.
Un application_id possédé et un Jeton de compte sont requis.
Si allow_overdraft=true, une Application au paiement à l’utilisation peut continuer à déduire de son propre solde sous zéro et ne basculera pas vers le solde global simplement parce que son propre solde est insuffisant.
Lorsqu’un repli se produit, le comportement de découvert est déterminé par l’Application globale qui paie effectivement.

Le repli global améliore la continuité, mais il élargit également le rayon d’impact financier. Activez-le comme politique délibérée au niveau du service, et non comme commodité par défaut.

¶ Tracez chaque appel de production par identifiant

AceDataCloud conserve les enregistrements d’appels API et les résumés de facturation pour les 60 derniers jours. Les corps de requête et de réponse sont conservés pendant 30 jours ; les enregistrements des jours 30 à 60 conservent les résumés, mais ne renvoient plus les corps complets metadata.request et metadata.response.

Interrogez les derniers enregistrements à :

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode "credential_id=${CREDENTIAL_ID}" \
  --data-urlencode 'perspective=both' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

Les filtres utiles incluent application_id, api_id, credential_id, status_code et les limites temporelles ISO 8601. Le paramètre perspective sépare trois vues :

billing — appels payés par le compte actuel.
actor — appels effectivement initiés par le compte actuel.
both — l’union par défaut des appels payés et initiés. Les champs clés pour la réponse aux incidents sont :

Champ	Utilisation opérationnelle
`credential_id`	Identifier la charge de travail exposée ou défaillante
`trace_id`	Enquêter sur une requête de bout en bout
`status_code`	Séparer les appels réussis et échoués
`elapsed`	Suivre la latence
`used_amount`	Utilisation calculée selon les règles d'origine
`original_amount`	Utilisation avant les remises de l'Application
`deducted_amount`	Montant final réellement déduit
`remaining_amount`	Quota de l'Application après le débit
`actor_user_id` / `user_id`	Distinguer l'appelant du compte responsable du paiement

Pour les requêtes volumineuses, utilisez des fenêtres plus courtes — de préférence un jour ou moins — et ajoutez des filtres. Si une requête identique est déjà en cours d'exécution, l'API peut renvoyer 429 usage_query_in_progress ; respectez Retry-After avec un backoff. Un 503 usage_query_timeout indique qu'il faut restreindre la requête plutôt que de la répéter immédiatement.

¶ Créez un flux de travail de rotation et d'incident avant d'en avoir besoin

Un guide de réponse pratique est :

Identifiez l'identifiant d'accès à partir de l'enregistrement d'utilisation ou de la configuration du service.
Contenez l'exposition en abaissant sa limite, en modifiant son expiration, en restreignant allowed_api_ids, ou en le révoquant.
Effectuez la rotation du secret et mettez à jour le gestionnaire de secrets.
Déployez la nouvelle valeur vers la charge de travail sans la journaliser.
Vérifiez les appels réussis sous l'ID d'identifiant d'accès attendu.
Examinez les enregistrements récents par identifiant d'accès, statut, API et ID de trace.
Révoquez les identifiants d'accès obsolètes après confirmation du basculement.

Créez des identifiants d'accès distincts pour le développement, la préproduction, la production, les tâches planifiées et les intégrations tierces. Cela rend la rotation locale et l'attribution claire. Une seule clé « production » partagée maximise à la fois le risque d'interruption et l'ambiguïté des investigations.

¶ Référence de contrôle recommandée

Pour chaque charge de travail de production :

¶ La gouvernance est une boucle

L'émission des identifiants d'accès, la surveillance des soldes et le traçage de l'utilisation ne doivent pas être gérés comme des tâches distinctes. Ensemble, ils forment une boucle de contrôle continue :

émettre de manière restreinte → surveiller l'Application qui paie → tracer les appels réels → effectuer rapidement une rotation ou une révocation.

Les API de gestion d'AceDataCloud exposent les champs nécessaires pour mettre en œuvre cette boucle sans confondre l'accès de gestion, l'accès d'exécution, le quota et l'attribution de facturation. Le résultat n'est pas simplement une clé API plus sûre ; c'est un système de production avec une exposition limitée et une utilisation explicable.

Gouvernance des API de production sur AceDataCloud : identifiants, contrôles de solde et surveillance de l’utilisation