Governança de API em Produção no AceDataCloud

Uma chave de API de produção não é apenas uma string secreta. Ela é um ponto de controle para quem pode chamar o quê, quanto pode consumir, quanto tempo o acesso dura, qual aplicação paga e como um incidente pode ser rastreado.

O AceDataCloud expõe esses controles em quatro camadas conectadas:

Emissão de credenciais — crie uma chave para uma Application específica.
Política de saldo da Application — determine de onde o uso é deduzido e o que acontece quando a cota está baixa.
Observabilidade de uso — rastreie status, custo, latência, API, Application e credencial.
Ciclo de vida da credencial — atualize restrições, alterne segredos e revogue o acesso.

Loop de controle de governança de API em produção

Este guia transforma as APIs de gerenciamento individuais da plataforma em um modelo operacional prático.

¶ Primeiro, separe os dois tipos de credenciais

O AceDataCloud usa credenciais diferentes para superfícies diferentes:

Credencial	Usada para	Host típico
Token de Conta / Token da Plataforma	Gerenciamento de conta: Applications, credenciais, saldos, uso, pedidos	`platform.acedata.cloud/api/v1/**`
Credencial de API	Chamar APIs de negócio para um serviço	`api.acedata.cloud/**`

Elas não são intercambiáveis. Uma credencial de API de negócio não deve ser usada para chamar endpoints de gerenciamento, e um Token da Plataforma não deve ser incorporado em uma aplicação como sua chave de API de negócio.

Essa separação cria um limite de segurança útil:

Mantenha Tokens da Plataforma em um ambiente de operações rigidamente controlado.
Dê a cada carga de trabalho sua própria Credencial de API.
Permita que serviços em tempo de execução chamem apenas as APIs de negócio de que precisam.
Permita que CI ou um serviço administrativo realize o gerenciamento de credenciais e saldos.

¶ Emita uma credencial por carga de trabalho e ambiente

Crie uma credencial com POST https://platform.acedata.cloud/api/v1/credentials/ usando um Token de Conta.

Uma solicitação mínima orientada à produção pode incluir um nome de exibição, limite de consumo independente, expiração e lista de permissões 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\"}
  }"

O contrato de criação suporta:

Campo	Finalidade de governança
`application_id`	Vincula o uso à Application de destino
`name`	Torna a carga de trabalho identificável em auditorias
`limited_amount`	Define um limite de uso de credencial independente; `null` significa sem limite independente
`expired_at`	Estabelece acesso automático limitado no tempo
`allowed_api_ids`	Restringe a credencial a APIs selecionadas
`host`	Armazena informações de host da credencial quando aplicável
`for_user_id`	Permite que um proprietário de Application emita credenciais delegadas para outro usuário
`tags` / `metadata`	Registra o contexto de ambiente, equipe, sistema ou tíquete de alteração

Uma matriz allowed_api_ids vazia é normalizada para nenhuma restrição. Não envie uma matriz vazia quando sua intenção for “não permitir nada”. Use uma lista de permissões de API real.

Serviços de API/Agent normalmente retornam uma credencial Token. Serviços de Proxy normalmente retornam uma identidade de nome de usuário/senha, e uma Application de Proxy permite apenas uma credencial.

Trate a resposta de criação como sensível. Salve o segredo imediatamente em um gerenciador de senhas ou gerenciador de segredos e não grave a resposta em logs. Clientes não devem depender de segredos em texto simples permanecerem recuperáveis posteriormente; APIs de ciclo de vida podem retornar valores mascarados.

¶ Use limites como controles de raio de impacto, não apenas para orçamentação

Um limited_amount no nível da credencial é útil para conter uma chave vazada ou uma carga de trabalho descontrolada, mas ele é apenas uma parte da governança de custos.

Uma hierarquia robusta é:

Limite de credencial: exposição máxima para uma carga de trabalho.
Saldo da Application: cota disponível para a Application de serviço assinada.
Política de saldo global: fallback opcional para Applications elegíveis de pagamento conforme o uso.
Autorização de cheque especial: uma autorização de plataforma separada e somente leitura que os clientes não podem habilitar por conta própria.

Não trate esses itens como equivalentes.

Por exemplo, mesmo quando uma Application tem cota disponível, um limite de credencial individual ainda pode bloquear a carga de trabalho. Por outro lado, habilitar o compartilhamento de saldo global pode permitir que uma Application elegível continue após seu próprio saldo ser insuficiente — mas isso não remove limites de credencial, desativação ou verificações de expiração.

¶ Monitore o saldo com unidade e status

Consulte uma Application com:

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

Os campos que importam operacionalmente incluem:

remaining_amount — cota atual da Application; um valor negativo indica cota pendente de liquidação.
used_amount — uso acumulado relatado para a Application.
service.unit — a unidade, como Crédito, Contagem ou Token.
disabled — se a Application está desativada.
expired_at — se o acesso à assinatura expirou.
allow_overdraft — indicação somente leitura de cheque especial aprovado pelo administrador.

Nunca presuma que o valor está em dólares americanos. Os limites de alerta devem ser definidos na unidade real do serviço.

Um saldo positivo por si só não comprova disponibilidade. Sua verificação de integridade deve avaliar saldo, disabled, expiração, limites de credencial e status do serviço. Para serviços de Proxy, a sincronização de saldo pode ser suspensa ou expirar, caso em que o saldo salvo mais recentemente pode ser retornado.

Uma verificação concisa em 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últiplos serviços, busque a lista de Applications uma vez e avalie cada item localmente, em vez de consultar cada endpoint de detalhes da Application em alta frequência.

¶ Decida explicitamente se o compartilhamento de saldo global é permitido

Applications elegíveis de pagamento conforme o uso podem ser configuradas para usar o saldo global da conta quando seu próprio saldo for 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}'

Use o valor allow_consume_global retornado como a fonte da verdade. Não presuma que o valor solicitado foi salvo.

Restrições importantes:

Applications Period não podem consumir o saldo global; o servidor mantém o campo como false.
São necessários um application_id de propriedade do usuário e um Token de Conta.
Se allow_overdraft=true, uma Application de pagamento conforme o uso pode continuar deduzindo de seu próprio saldo abaixo de zero e não mudará para o saldo global meramente porque seu próprio saldo é insuficiente.
Quando ocorre o fallback, o comportamento de cheque especial é determinado pela Application global que realmente paga.

O fallback global melhora a continuidade, mas também amplia o raio de impacto financeiro. Habilite-o como uma política deliberada no nível do serviço, não como uma conveniência padrão.

¶ Rastreie cada chamada de produção por credencial

O AceDataCloud retém registros de chamadas de API e resumos de faturamento pelos 60 dias mais recentes. Corpos de solicitação e resposta são retidos por 30 dias; registros dos dias 30–60 mantêm resumos, mas não retornam mais os corpos completos de metadata.request e metadata.response.

Consulte os registros mais recentes em:

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

Filtros úteis incluem application_id, api_id, credential_id, status_code e limites de tempo ISO 8601. O parâmetro perspective separa três visualizações:

billing — chamadas pagas pela conta atual.
actor — chamadas realmente iniciadas pela conta atual.
both — a união padrão de chamadas pagas e iniciadas. Os principais campos para resposta a incidentes são:

Campo	Uso operacional
`credential_id`	Identificar a carga de trabalho exposta ou com mau funcionamento
`trace_id`	Investigar uma solicitação de ponta a ponta
`status_code`	Separar chamadas bem-sucedidas e com falha
`elapsed`	Acompanhar a latência
`used_amount`	Uso calculado segundo as regras originais
`original_amount`	Uso antes dos descontos da Application
`deducted_amount`	Valor final efetivamente deduzido
`remaining_amount`	Cota da Application após a cobrança
`actor_user_id` / `user_id`	Distinguir o chamador da conta responsável pelo pagamento

Para consultas grandes, use janelas menores — de preferência um dia ou menos — e adicione filtros. Se uma consulta idêntica já estiver em execução, a API poderá retornar 429 usage_query_in_progress; siga Retry-After com backoff. Um 503 usage_query_timeout é um sinal para restringir a solicitação em vez de repeti-la imediatamente.

¶ Crie um fluxo de rotação e incidentes antes de precisar dele

Um playbook prático de resposta é:

Identifique a credencial a partir do registro de uso ou da configuração do serviço.
Contenha a exposição reduzindo seu limite, alterando sua expiração, restringindo allowed_api_ids ou revogando-a.
Rotacione o segredo e atualize o gerenciador de segredos.
Implante o novo valor na carga de trabalho sem registrá-lo em logs.
Verifique chamadas bem-sucedidas sob o ID de credencial esperado.
Revise registros recentes por credencial, status, API e ID de rastreamento.
Revogue credenciais obsoletas após a confirmação da transição.

Crie credenciais separadas para desenvolvimento, homologação, produção, tarefas agendadas e integrações de terceiros. Isso torna a rotação local e a atribuição clara. Uma única chave compartilhada de “produção” maximiza tanto o risco de interrupção quanto a ambiguidade investigativa.

¶ Linha de base de controle recomendada

Para cada carga de trabalho de produção:

¶ A governança é um ciclo

A emissão de credenciais, o monitoramento de saldo e o rastreamento de uso não devem ser gerenciados como tarefas separadas. Juntos, eles formam um ciclo contínuo de controle:

emita de forma restrita → monitore a Application pagadora → rastreie chamadas reais → rotacione ou revogue rapidamente.

As APIs de gerenciamento da AceDataCloud expõem os campos necessários para implementar esse ciclo sem confundir acesso de gerenciamento, acesso em tempo de execução, cota e atribuição de faturamento. O resultado não é apenas uma chave de API mais segura; é um sistema de produção com exposição limitada e uso explicável.

Governança de API de Produção no AceDataCloud: Credenciais, Controles de Saldo e Monitoramento de Uso