Autenticação

Envie a chave no cabeçalho Authorization em todos os pedidos. As chaves têm o prefixo vokse_sk_, o que as torna fáceis de detetar nos registos (trate-as como palavras-passe e nunca as coloque no repositório).

Authorization: Bearer vokse_sk_3f8a…

Abra Definições → Chaves de API na aplicação vokse e crie uma chave. O segredo é mostrado uma única vez, no momento da criação, por isso copie-o de imediato. Dê a cada integração a sua própria chave, para poder revogar uma sem afetar as restantes.

1. Vá a Definições → Chaves de API.
2. Clique em «Criar chave» e dê-lhe o nome da integração.
3. Selecione os âmbitos mínimos de que a integração precisa.
4. Copie o segredo. Só é mostrado uma vez.

Cada chave é criada dentro de um agregado e só pode agir sobre ele. As rotas com âmbito levam o id do agregado no caminho, mas raramente precisa de o procurar: o segmento literal current resolve sempre para o agregado a que a chave pertence. Se quiser mesmo o id real, obtenha-o uma vez:

curl -H "Authorization: Bearer vokse_sk_3f8a…" \     https://api.vokse.ai/households/current

Todos os exemplos desta referência usam current, por isso correm tal como estão, só com a sua chave. Prefere ids explícitos? Copie o seu em Definições → Membros, na aplicação, ou envie-o no cabeçalho X-Household-Id em vez de o pôr no caminho.

Cada chave leva consigo um conjunto de âmbitos. Um pedido só é permitido se a chave tiver o âmbito que o endpoint exige (assinalado em cada um deles). Os âmbitos dividem-se em três classes:

• read:* dá acesso só de leitura a um recurso (seguro, idempotente).
• write:* permite criar, atualizar e eliminar num recurso.
• ai:* permite invocar funcionalidades de IA; o consumo é descontado do seu limite mensal.

Pode dar uma data de validade à chave no momento da criação. A partir daí, os pedidos falham com API_KEY_EXPIRED. Para substituir uma chave, crie uma nova, coloque-a em produção e só depois revogue a antiga. Não há paragens forçadas. As chaves revogadas deixam de funcionar de imediato.