Autenticação

Chaves de API

A chave tem o formato int8_live_ seguido de 40 letras e números. Crie quantas quiser em console › Chaves de API; cada uma tem nome, escopos, whitelist de IP e data de expiração. O console mostra só o começo e o fim (int8_live_Ab…wxyz): a chave inteira aparece uma vez, na criação, e a int8labs guarda só um hash dela.

Mande a chave no cabeçalho Authorization:

curl https://api.int8labs.com/v1/balance \
  -H "Authorization: Bearer $INT8_API_KEY"

Escopos

Cada chave libera um ou mais produtos. Uma rota fora dos escopos da chave volta 403 scope_denied.

• stt: transcrição em lote (/v1/stt/transcriptions) e ao vivo (/v1/stt/stream).
• tts: voz (POST /v1/tts e /v1/tts/stream).
• avatar: avatar (/v1/avatar/stream).

GET /v1/balance e POST /v1/tokens aceitam qualquer escopo. GET /v1/health, GET /v1/models e GET /v1/voices nem pedem chave.

Whitelist de IP

Com a whitelist preenchida, a chave só vale a partir dos IPs listados (IPv4, IPv6 ou faixas CIDR como 203.0.113.0/24, até 50 entradas). Vazia, vale de qualquer lugar. Um IP de fora recebe 403 ip_not_allowed.

A whitelist vale onde a chave é usada: no seu servidor, inclusive na emissão de tokens temporários. O token em si não confere IP, porque o navegador de cada usuário tem o seu.

Expiração e rotação

Na criação você escolhe 30 dias, 90 dias, 1 ano, uma data (de 1 a 730 dias) ou "Não expira". Chave vencida recebe 401 api_key_expired.

Para trocar uma chave sem parar o serviço:

1. Crie a chave nova com os mesmos escopos e a mesma whitelist (em Chaves de API, "Duplicar configuração").
2. Ponha a chave nova no seu servidor e faça o deploy.
3. Confira em "Último uso" que a chave velha parou de receber chamadas e revogue.

A revogação vale em até 15 segundos para pedidos novos. Nos WebSockets abertos, a voz e o avatar recusam a próxima fala, e a transcrição ao vivo fecha em até 75 segundos (60 s entre conferências mais o cache de 15 s), com api_key_revoked e o código 4401.

Tokens temporários

O navegador e o SDK do avatar falam direto com a API usando um token int8_tmp_… que o seu servidor pede com a chave. O token dura de 60 s a 1 hora (padrão: 10 minutos), carrega no máximo os escopos da chave e para de valer junto com ela.

curl https://api.int8labs.com/v1/tokens \
  -H "Authorization: Bearer $INT8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 600, "scopes": ["avatar"]}'

No navegador, o token vai no cabeçalho Authorization: Bearer int8_tmp_… (REST) ou na URL do WebSocket, em ?token=int8_tmp_…, que é o único jeito de um WebSocket do navegador se autenticar. Um token não emite outro token: POST /v1/tokens com um token volta 403 scope_denied.

Boas práticas

• Uma chave por ambiente (produção, homologação) e por serviço, com só os escopos que ele usa.
• Whitelist com os IPs de saída dos seus servidores.
• Chaves de produção com expiração e rotação no calendário.
• Nunca registre o cabeçalho Authorization em log. A API também não registra.
• No navegador, só tokens temporários com o menor escopo e o menor prazo que servem.