Gobernanza de API de producción en AceDataCloud

Una clave de API de producción no es solo una cadena secreta. Es un punto de control para quién puede llamar a qué, cuánto pueden consumir, cuánto dura el acceso, qué aplicación paga y cómo se puede rastrear un incidente.

AceDataCloud expone esos controles en cuatro capas conectadas:

  1. Emisión de credenciales — crear una clave para una Aplicación específica.
  2. Política de saldo de la Aplicación — determinar de dónde se deduce el uso y qué sucede cuando la cuota es baja.
  3. Observabilidad de uso — rastrear estado, costo, latencia, API, Aplicación y credencial.
  4. Ciclo de vida de credenciales — actualizar restricciones, rotar secretos y revocar acceso.

Bucle de control de gobernanza de API de producción

Esta guía convierte las API de administración individuales de la plataforma en un modelo operativo práctico.

Primero, separe los dos tipos de credenciales

AceDataCloud utiliza diferentes credenciales para diferentes superficies:

Credencial Se utiliza para Host típico
Token de Cuenta / Token de Plataforma Administración de cuentas: Aplicaciones, credenciales, saldos, uso, pedidos platform.acedata.cloud/api/v1/**
Credencial de API Llamar a API de negocio para un servicio api.acedata.cloud/**

No son intercambiables. Una credencial de API de negocio no debe utilizarse para llamar a endpoints de administración, y un Token de Plataforma no debe incrustarse en una aplicación como su clave de API de negocio.

Esta separación crea un límite de seguridad útil:

  • Mantenga los Tokens de Plataforma en un entorno de operaciones estrictamente controlado.
  • Dé a cada carga de trabajo su propia Credencial de API.
  • Permita que los servicios de tiempo de ejecución llamen solo a las API de negocio que necesitan.
  • Permita que CI o un servicio administrativo realice la administración de credenciales y saldos.

Emita una credencial por carga de trabajo y entorno

Cree una credencial con POST https://platform.acedata.cloud/api/v1/credentials/ utilizando un Token de Cuenta.

Una solicitud mínima orientada a producción puede incluir un nombre para mostrar, un límite de consumo independiente, vencimiento y una lista de permitidos de 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\"}
  }"

El contrato de creación admite:

Campo Propósito de gobernanza
application_id Vincula el uso a la Aplicación de destino
name Hace que la carga de trabajo sea identificable en auditorías
limited_amount Establece un límite de uso de credencial independiente; null significa que no hay límite independiente
expired_at Establece acceso automático limitado en el tiempo
allowed_api_ids Restringe la credencial a API seleccionadas
host Almacena información de host de la credencial cuando corresponde
for_user_id Permite que un propietario de Aplicación emita credenciales delegadas para otro usuario
tags / metadata Registra el contexto de entorno, equipo, sistema o ticket de cambio

Un arreglo vacío de allowed_api_ids se normaliza como sin restricción. No envíe un arreglo vacío cuando su intención sea “no permitir nada”. Utilice una lista de permitidos de API real.

Los servicios de API/Agente normalmente devuelven una credencial de Token. Los servicios Proxy normalmente devuelven una identidad de nombre de usuario/contraseña, y una Aplicación Proxy permite solo una credencial.

Trate la respuesta de creación como confidencial. Guarde el secreto inmediatamente en un administrador de contraseñas o administrador de secretos y no escriba la respuesta en registros. Los clientes no deben depender de que los secretos en texto plano sigan siendo recuperables más adelante; las API de ciclo de vida pueden devolver valores enmascarados.

Utilice los límites como controles de radio de impacto, no solo para presupuestos

Un limited_amount a nivel de credencial es útil para contener una clave filtrada o una carga de trabajo descontrolada, pero es solo una parte de la gobernanza de costos.

Una jerarquía sólida es:

  • Límite de credencial: exposición máxima para una carga de trabajo.
  • Saldo de la Aplicación: cuota disponible para la Aplicación de servicio suscrita.
  • Política de saldo global: respaldo opcional para Aplicaciones elegibles de pago por uso.
  • Autorización de sobregiro: una autorización de plataforma separada y de solo lectura que los clientes no pueden habilitar por sí mismos.

No los trate como equivalentes.

Por ejemplo, incluso cuando una Aplicación tiene cuota disponible, un límite de credencial individual aún puede bloquear la carga de trabajo. Por el contrario, habilitar el uso compartido del saldo global puede permitir que una Aplicación elegible continúe después de que su propio saldo sea insuficiente, pero no elimina los límites de credenciales, la deshabilitación ni las comprobaciones de vencimiento.

Supervise el saldo con unidad y estado

Consulte una Aplicación con:

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

Los campos que importan operativamente incluyen:

  • remaining_amount — cuota actual de la Aplicación; un valor negativo indica cuota pendiente de liquidación.
  • used_amount — uso acumulado informado para la Aplicación.
  • service.unit — la unidad, como Crédito, Conteo o Token.
  • disabled — si la Aplicación está deshabilitada.
  • expired_at — si el acceso de suscripción ha vencido.
  • allow_overdraft — indicación de solo lectura de sobregiro aprobado por el administrador.

Nunca suponga que el importe está en dólares estadounidenses. Los umbrales de alerta deben definirse en la unidad real del servicio.

Un saldo positivo por sí solo no demuestra disponibilidad. Su comprobación de estado debe evaluar el saldo, disabled, el vencimiento, los límites de credenciales y el estado del servicio. Para los servicios Proxy, la sincronización de saldo puede suspenderse o agotarse el tiempo de espera, en cuyo caso se puede devolver el saldo guardado más recientemente.

Una comprobación concisa en Python:

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}")

Para múltiples servicios, obtenga la lista de Aplicaciones una vez y evalúe cada elemento localmente en lugar de sondear cada endpoint de detalles de Aplicación con alta frecuencia.

Decida explícitamente si se permite el uso compartido del saldo global

Las Aplicaciones elegibles de pago por uso se pueden configurar para utilizar el saldo global de la cuenta cuando su propio saldo sea insuficiente:

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}'

Utilice el valor allow_consume_global devuelto como fuente de verdad. No suponga que se guardó el valor solicitado.

Restricciones importantes:

  • Las Aplicaciones Period no pueden consumir el saldo global; el servidor mantiene el campo en false.
  • Se requiere un application_id propio y un Token de Cuenta.
  • Si allow_overdraft=true, una Aplicación de pago por uso puede continuar deduciendo de su propio saldo por debajo de cero y no cambiará al saldo global simplemente porque su propio saldo sea insuficiente.
  • Cuando ocurre el respaldo, el comportamiento de sobregiro lo determina la Aplicación global que realmente paga.

El respaldo global mejora la continuidad, pero también amplía el radio de impacto financiero. Habilítelo como una política deliberada a nivel de servicio, no como una comodidad predeterminada.

Rastree cada llamada de producción por credencial

AceDataCloud conserva registros de llamadas de API y resúmenes de facturación durante los 60 días más recientes. Los cuerpos de solicitud y respuesta se conservan durante 30 días; los registros de los días 30–60 conservan resúmenes, pero ya no devuelven cuerpos completos de metadata.request y metadata.response.

Consulte los registros más recientes en:

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}"

Los filtros útiles incluyen application_id, api_id, credential_id, status_code y límites de tiempo ISO 8601. El parámetro perspective separa tres vistas:

  • billing — llamadas pagadas por la cuenta actual.
  • actor — llamadas realmente iniciadas por la cuenta actual.
  • both — la unión predeterminada de llamadas pagadas e iniciadas. Los campos clave para la respuesta a incidentes son:
Campo Uso operativo
credential_id Identificar la carga de trabajo expuesta o con mal funcionamiento
trace_id Investigar una solicitud de extremo a extremo
status_code Separar las llamadas exitosas de las fallidas
elapsed Rastrear la latencia
used_amount Uso calculado bajo las reglas originales
original_amount Uso antes de los descuentos de la Aplicación
deducted_amount Cantidad final realmente deducida
remaining_amount Cuota de la Aplicación después del cargo
actor_user_id / user_id Distinguir al llamante de la cuenta responsable del pago

Para consultas grandes, use ventanas más cortas, preferiblemente de un día o menos, y agregue filtros. Si ya se está ejecutando una consulta idéntica, la API puede devolver 429 usage_query_in_progress; respete Retry-After con retroceso. Un 503 usage_query_timeout es una señal para acotar la solicitud en lugar de repetirla inmediatamente.

Cree un flujo de trabajo de rotación e incidentes antes de necesitarlo

Un manual de respuesta práctico es:

  1. Identifique la credencial a partir del registro de uso o la configuración del servicio.
  2. Contenga la exposición reduciendo su límite, cambiando su vencimiento, restringiendo allowed_api_ids o revocándola.
  3. Rote el secreto y actualice el gestor de secretos.
  4. Implemente el nuevo valor en la carga de trabajo sin registrarlo en los logs.
  5. Verifique las llamadas exitosas bajo el ID de credencial esperado.
  6. Revise los registros recientes por credencial, estado, API e ID de rastreo.
  7. Revoque las credenciales obsoletas después de confirmar la transición.

Cree credenciales separadas para desarrollo, staging, producción, trabajos programados e integraciones de terceros. Esto hace que la rotación sea local y la atribución clara. Una única clave compartida de “producción” maximiza tanto el riesgo de interrupción como la ambigüedad investigativa.

Línea base de control recomendada

Para cada carga de trabajo de producción:

  • Credencial API dedicada; sin uso compartido entre entornos.
  • Nombre descriptivo y metadatos de propiedad.
  • Lista de permitidos de API que contenga solo los ID de endpoint requeridos.
  • Límite de consumo independiente proporcional a la carga de trabajo esperada.
  • Fecha de vencimiento con una ventana de renovación planificada.
  • Secreto almacenado en un gestor de secretos y excluido de los logs.
  • Alerta de saldo de la Aplicación en la unidad de servicio correcta.
  • Comprobaciones de deshabilitación y vencimiento, no solo del saldo.
  • Decisión explícita sobre allow_consume_global.
  • Panel de uso filtrado por Aplicación y credencial.
  • ID de rastreo capturados en los logs de la aplicación.
  • Procedimiento documentado de rotación y revocación.

La gobernanza es un ciclo

La emisión de credenciales, el monitoreo de saldo y el rastreo de uso no deben gestionarse como tareas separadas. Juntos forman un ciclo de control continuo:

emitir de forma restringida → monitorear la Aplicación que paga → rastrear las llamadas reales → rotar o revocar rápidamente.

Las API de gestión de AceDataCloud exponen los campos necesarios para implementar ese ciclo sin confundir el acceso de gestión, el acceso en tiempo de ejecución, la cuota y la atribución de facturación. El resultado no es simplemente una clave API más segura; es un sistema de producción con exposición limitada y uso explicable.

Recursos oficiales