Credenciais e provedores

A chave é validada no provedor ao ser salva e fica no Vault. Nenhuma leitura devolve o segredo: só last4. Provedores aceitos:

Credenciais

GET /ai/credentials

Escopo agents:read

Query customer_id. Retorna todas as credenciais do Cliente, com os usos de cada uma.

POST /ai/credentials

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "provider": "openai",
  "label": "OpenAI produção",
  "key": "CHAVE_DO_SEU_PROVEDOR"
}

Responde 201 com a credencial. Confira validation_status (valid, invalid ou pending) e last_error: só uma credencial válida e ativa pode ser publicada.

{
  "id": "22222222-2222-4222-8222-222222222222",
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "provider": "openai",
  "label": "OpenAI produção",
  "last4": "a1B2",
  "revision": "1",
  "active": true,
  "validation_status": "valid",
  "validated_at": "2026-09-25T13:00:00.000Z",
  "last_error": null,
  "models": [
    "MODELO_A",
    "MODELO_B"
  ],
  "usage_count": 1,
  "usages": [
    {
      "kind": "agent_version",
      "id": "55555555-5555-4555-8555-555555555555",
      "label": "Atendimento · v3"
    }
  ]
}

GET /ai/credentials/{id}

Escopo agents:read

Query customer_id. Mesmo formato do item da lista.

PATCH /ai/credentials/{id}

Escopo agents:write

Corpo com customer_id e expected_revision, mais uma das formas:

• label e/ou active: renomeia ou ativa/desativa;
• key sozinho: troca o segredo e valida de novo. key junto de label ou active é recusado com 422 invalid.

Trocar a chave cria uma nova revisão.

POST /ai/credentials/{id}/revalidate

Escopo agents:write

Corpo {customer_id, expected_revision}. Consulta o provedor de novo e atualiza models e validation_status.

DELETE /ai/credentials/{id}

Escopo agents:write

Corpo {customer_id, expected_revision}. Responde 204. Uma credencial referenciada por versão, roteador ou finalidade retorna 409 in_use: troque os vínculos antes.

Confirmação de uso de dados

Se a Conta já conectou o Google Agenda, cada revisão de credencial precisa de uma confirmação das condições de uso de dados do provedor antes de qualquer inferência. Sem ela, testes, execuções e consultas retornam 409 google_data_use_ack_required. Trocar a chave cria uma revisão nova e exige nova confirmação. A confirmação pode ser feita por qualquer membro da Conta no painel, em Configurações › Provedores e chaves, Credenciais › Editar (ou Confirmar uso dos dados, para quem é Operador); pela API, com uma chave live que tenha agents:write e tenha sido criada por um Administrador (outra chave recebe 403 forbidden). Confira as condições do provedor antes de confirmar; a API registra a chave de API como autora.

GET /ai/credentials/{id}/data-use

Escopo agents:read

Query customer_id. Retorna credential_revision, policy_version, requires_ack (a Conta exige a confirmação), acknowledged (há confirmação ativa para a revisão atual), accepted_at, accepted_by_user_id ou accepted_by_api_key_id e evidence_note.

POST /ai/credentials/{id}/data-use

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, expected_revision, policy_version: "2026-09-24", confirmed: true, evidence}. evidence (10 a 2000 caracteres) descreve como as condições foram verificadas no provedor; texto com chave, token ou senha é recusado com 422 invalid. Repetir para a mesma revisão não cria outro registro. Responde com o mesmo formato do GET.

POST /ai/credentials/{id}/data-use/revoke

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, expected_revision, reason} (reason com 10 a 2000 caracteres). A evidência anterior é preservada; as próximas inferências com a credencial param enquanto a Conta exigir a confirmação.

Finalidades

Cada chamada de modelo tem uma finalidade. O atendimento, o operador e o roteador usam o que foi publicado na versão ou no roteador. As outras usam o vínculo configurado aqui.

GET /ai/providers

Escopo agents:read

Query customer_id. Retorna providers, purposes (rótulos), configurable_purposes, configuration_sources (onde ficam agent_turn, agent_operator e router), credentials e bindings.

PUT /ai/providers

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "purpose": "embedding",
  "provider": "openai",
  "model": "text-embedding-3-small",
  "credential_id": "22222222-2222-4222-8222-222222222222",
  "fallback": null
}

Retorna o vínculo salvo. embedding aceita apenas OpenAI text-embedding-3-small; transcription exige modelo de transcrição; vision recusa modelos que o catálogo indica sem entrada de imagem.

DELETE /ai/providers

Escopo agents:write

Corpo {customer_id, purpose}. Responde 204. A finalidade volta a herdar o padrão, quando herda.

Modelos e catálogo

GET /ai/providers/{provider}/models

Escopo agents:read

Query customer_id e credential_id. Lista os modelos que a credencial validada enxerga, com capabilities (text, transcription ou embedding).

GET /ai/providers/catalog

Escopo agents:read

Query customer_id. Último retrato do catálogo de cada credencial, sem chaves.

POST /ai/providers/catalog

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, credential_id, expected_revision}, com a revisão da credencial ("1" ou mais). Consulta o provedor com a sua chave e responde 201 com o retrato. Preços do catálogo são sugestões: não alteram as tarifas de Uso e orçamento.

Visão geral do Agente de IA · Próxima: Agentes e versões