Chaves de API
Nesta página
As chaves de API permitem que o seu próprio software — ou qualquer sistema de terceiros com suporte a BYOK (Bring Your Own Key) — use os modelos publicados pelo Performance Hub. As chaves são gerenciadas em Settings (engrenagem) → Service Access & API Keys. Você precisa ser um Organisation Administrator para gerenciá-las.
"Forneça chaves de API para que softwares e sistemas de terceiros que suportam BYOK (Bring Your Own Key) possam se conectar aos models publicados pelo Performance Hub."
Figura 1: A lista de chaves de API: rótulo, chave mascarada, status, gasto e limites, modelos, último uso e as ações de linha
A lista de chaves
| Coluna | Significado |
|---|---|
| Label | O nome opcional que você deu à chave. |
| Key | A chave mascarada (por exemplo, phk_7Qm2…Xa9LkP) — o segredo completo nunca é exibido novamente após a criação. |
| Status | Active, Provisioning… (brevemente, enquanto uma nova chave é configurada) ou Disabled (revogada; a linha fica esmaecida). |
| Spend / limits | O gasto vitalício e o progresso em relação a eventuais limites de gasto definidos na chave. |
| Models | all ou a quantidade de modelos aos quais a chave está restrita. |
| Last used | Quando a chave fez a última solicitação. |
| Actions | Edit, Rotate, Revoke (ou Re-activate), Delete. |
Se você usa Workflows, uma linha Workflows mostra Managed service no lugar de uma chave mascarada. Sem nenhuma chave, a lista mostra "No API keys yet."
Criando uma chave
Clique em Create key. A gaveta Create API key é aberta:
Figura 2: A gaveta Create API key: rótulo, tipo de conexão, limites de gasto, limites de taxa, restrição de modelos e substituição de proteções
| Configuração | Comportamento |
|---|---|
| Label (optional) | Um nome para a chave, geralmente o do sistema ao qual ela se destina (por exemplo, Hotel Concierge App, Clinic Intake Assistant ou Booking Website). Altamente recomendado — os rótulos são a forma como o uso é atribuído em Activity e Logs. |
| Connection type | API key — "Generic API keys remain in the API Keys list." External agent — "External agents appear under Connected Services and use this key to authenticate." Definido quando a chave é criada; não pode ser alterado depois. |
| Set spend limits for this key | "Set any combination of daily, monthly and lifetime caps for this key." — Daily limit ("Resets at the start of each day (facility timezone)."), Monthly limit ("Resets on the 1st of each month (facility timezone).") e Lifetime cap ("Total spend over the lifetime of this key. Never resets."). |
| Rate limits (optional) | "Cap requests and tokens per minute for this key. Leave blank for unlimited." — Requests / min e Tokens / min. |
| Restrict models for this key | "Only the selected models will be usable with this key." Escolha entre os modelos habilitados na instalação. |
| Override facility guardrails for this key | "Select none to explicitly disable guardrails for this key." Quando ativado, esta chave usa a sua própria seleção de proteções em vez da seleção da instalação — incluindo "none". Consulte Guardrails. |
Clique em Create key.
O segredo exibido uma única vez
A nova chave é exibida uma única vez, na caixa de diálogo Copy your API key:
Figura 3: A nova chave é exibida uma única vez: copie-a antes de fechar a caixa de diálogo
"Esta é a única vez que a chave completa é exibida. Guarde-a em um local seguro."
Copie-a para o seu gerenciador de segredos antes de clicar em Done. Depois que essa caixa de diálogo for fechada, somente a forma mascarada será exibida. Se você perder o segredo, use Rotate na chave para obter uma nova.
Editando uma chave
Clique na linha de uma chave (ou no lápis Edit) para abrir a gaveta Configure API key — com as mesmas configurações da criação (rótulo, limites de gasto, limites de taxa, restrição de modelos, substituição de proteções):
Figura 4: A gaveta Configure API key
As alterações entram em vigor instantes depois de salvas. Quando uma chave tem limites diários/mensais, a linha dela mostra o uso em relação a eles (Today, This month, Lifetime) e um selo Limit reached quando um deles é atingido.
Ciclo de vida da chave: rotacionar, revogar, excluir
Cada ação tem uma caixa de diálogo de confirmação que descreve exatamente o que vai acontecer:
| Ação | Efeito | Texto da confirmação |
|---|---|---|
| Rotate | Emite um novo segredo (exibido uma única vez) com as mesmas configurações; o segredo antigo deixa de funcionar imediatamente. | "A new key will be issued and the current key will stop working immediately." "You will need to reconfigure any services still using the old key. This cannot be undone." |
| Revoke | Desativa a chave imediatamente, de forma reversível. | "This key will be disabled immediately and any services using it will stop working. You can re-activate it again later." |
| Re-activate | Restaura uma chave revogada (com o mesmo segredo). | Nenhuma — é executada imediatamente. |
| Delete | Remove a chave permanentemente. | "This permanently deletes the key and any services using it will stop working. This cannot be undone." |
Figura 5: A confirmação Delete API key
Qual usar: rotacione se suspeitar de um vazamento (o serviço mantém as configurações e o histórico — basta atualizar o segredo); revogue para pausar um sistema temporariamente; exclua somente quando a integração deixar de existir de vez.
Conectando-se com uma chave
O cartão Connecting to the API, abaixo da lista de chaves, mostra o URL base e um exemplo de solicitação para copiar e colar no seu ambiente. Consulte Como conectar o seu aplicativo para ver o guia de início rápido completo, com exemplos de SDK e tratamento de erros.