# Chaves de IA

Criar chaves do Router IA com teto de gasto, token visível uma única vez, limites para empresas novas, revogação e reativação.

Fonte: https://ardumaker.com/pt/docs/claves-ia/

- Categoria: Inteligência artificial e agentes
- Estado: Disponível
- Requisitos: Ser admin da empresa para criar, revogar ou reativar; Um meio de pagamento ativo na empresa; Pelo menos 20 EUR de saldo, e saldo suficiente para cobrir o teto pedido
- Ferramentas MCP (Só leem): `listar_claves_router_ia`, `ver_clave_router_ia`
- Ferramentas MCP (Escrevem ou modificam): `crear_clave_router_ia`, `revocar_clave_router_ia`, `reactivar_clave_router_ia`, `crear_token_search_api`, `revocar_token_search_api`, `reactivar_token_search_api`

## O que permite fazer?

- Criar chaves do [Router IA](https://ardumaker.com/pt/docs/router-ia) com um nome, um teto de gasto em USD e um período de reinício do teto (`daily`, `weekly` ou `monthly`).
- Revogar uma chave: deixa de funcionar no OpenRouter e registra-se o gasto pendente.
- Reativar uma chave revogada.
- Listar as chaves e ver o seu uso sem nunca expor o token.

## Quando convém usar?

- Uma chave por aplicação ou ambiente, para separar gastos e poder cortar uma sem afetar as outras.
- Quando um token foi divulgado: revogá-lo e criar um novo.
- Para limitar quanto pode gastar uma integração por dia, semana ou mês.

## Como funciona na ArduMaker?

### Criar

1. Verifica-se que quem pede é admin da empresa e que a empresa tem um meio de pagamento ativo.
2. Verifica-se o saldo: pelo menos 20 EUR, e que chegue para o teto pedido.
3. Se a empresa for nova (menos de 7 dias ou sem um pagamento autorizado): no máximo 5 chaves ativas, teto diário até 30 USD e só reinício diário.
4. Cria-se a chave no OpenRouter. Sem `limit`, nasce com um teto de 30 USD que se reinicia todos os dias.
5. A resposta traz o token completo **uma única vez**. Depois não volta a ser mostrado por MCP nem nas listagens.

> **PRECAUCION:** `limit` é o **teto de gasto** da chave, não um tamanho de página. Enviar 50 cria uma chave que pode gastar 50 USD por período.

### Revogar e reativar

- Revogar sincroniza o uso (para registrar o pendente), desativa a chave no OpenRouter e marca-a como eliminada. A linha não é apagada.
- Reativar volta a ativá-la no OpenRouter e limpa a marca de pausa por saldo.
- Uma chave pausada por saldo negativo ou por verificação de identidade não está revogada: reativa-se sozinha quando a causa se resolve.

Os tokens da [Search API](https://ardumaker.com/pt/docs/search-api) seguem regras parecidas (admin, meio de pagamento, 20 EUR de saldo, token visível uma vez, revogar e reativar), mas não têm teto de gasto próprio.

## O que muda realmente?

- No OpenRouter: a chave, com um nome que inclui a empresa e o nome escolhido.
- Na ArduMaker: a chave fica associada a um serviço da empresa; revogá-la remove esse serviço.
- No histórico da empresa: o consumo, sob medida que é sincronizado.

## Esquema

**Ciclo de vida de uma chave**

```text
Criada (token visível uma vez)
  ↓
Ativa (gasta até ao seu teto por período)
  ↓
Pausada (saldo negativo ou verificação; volta sozinha)
  ↓
Revogada (desativada; pode ser reativada)
```

## Resultado esperado

- `crear_clave_router_ia` devolve `id`, `name`, `api_key` (o token) e um aviso para o salvar já.
- `ver_clave_router_ia` devolve uso, teto, restante e reinício; com permissões de admin, também o detalhe de gastos.
- Uma chave revogada deixa de aparecer como ativa e o OpenRouter rejeita-a.

## Erros e resolução

| Resposta | Causa | O que fazer |
| --- | --- | --- |
| 403 | Só um admin da empresa cria, revoga ou reativa | Pedir a um admin |
| 400 sem meio de pagamento | A empresa não tem um meio de pagamento ativo | Acrescentar um |
| 400 saldo | Menos de 20 EUR, ou o teto pedido ultrapassa o saldo | Carregar ou pedir um teto menor |
| 400 empresa nova | Mais de 5 chaves, teto diário acima de 30 USD ou reinício não diário | Liberta-se com mais de 7 dias e um pagamento autorizado |
| 400 já revogada / já ativa | A chave já estava nesse estado | Nada a fazer |
| Erro do OpenRouter | O OpenRouter rejeitou ou não respondeu | Tentar mais tarde |

> **PELIGRO:** `crear_clave_router_ia` não é idempotente por si só: uma repetição sem a mesma `idempotency_key` cria uma segunda chave. Com a mesma chave de idempotência recupera-se o resultado original (incluindo o token) durante 24 horas.

## Relação com MCP

Sim, nos perfis `/mcp` e `/mcp/infra`.

| Ferramenta | Tipo | Notas |
| --- | --- | --- |
| `listar_claves_router_ia`, `ver_clave_router_ia` | Leitura | Nunca devolvem o token |
| `crear_clave_router_ia` | Escrita | Admin; devolve o token uma vez; aceita `idempotency_key` |
| `revocar_clave_router_ia` | Destrutiva, reversível | Admin |
| `reactivar_clave_router_ia` | Escrita | Admin |
| `crear_token_search_api`, `revocar_token_search_api`, `reactivar_token_search_api` | Escrita | Tokens da Search API, mesmas regras de admin |

O token é um dado sensível na resposta: o agente tem de o entregar ao seu humano e não o publicar. Referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs) e exemplos em [/mcp/ia](https://ardumaker.com/pt/mcp/ia).

## Funcionalidades relacionadas

- [Router IA](https://ardumaker.com/pt/docs/router-ia/)
- [Search API](https://ardumaker.com/pt/docs/search-api/)
- [Saldo por empresa](https://ardumaker.com/pt/docs/saldo-por-empresa/)
- [Servidor MCP](https://ardumaker.com/pt/docs/servidor-mcp/)