Autenticação
O formato das chaves, onde guardá-las, restrições por chave, rotação e o que fazer se uma chave vazar.
Toda requisição à API leva uma chave de API no cabeçalho Authorization:
Authorization: Bearer sk-popnow-3f9c0a…Não há outra forma de autenticar: chaves na query string da URL nunca são aceitas, e o seu login no popnow.ai não vale na API.
Uma exceção: as rotas compatíveis com OpenAI em /v1 também leem a chave do cabeçalho x-api-key, então clientes no estilo OpenAI funcionam sem mudanças. As rotas nativas /api/v1 leem apenas Authorization.
Como é uma chave
Uma chave é sk-popnow- seguido de 48 caracteres hexadecimais minúsculos. Depois de criada, o console da API só mostra os primeiros caracteres, então uma chave perdida não pode ser recuperada — basta criar outra.
Crie uma chave
- Entre em popnow.ai e abra o console da API.
- Escolha Create key e dê um nome que diga onde ela vai ficar, como
production-backend. - Copie na hora. Ela só aparece uma vez.
Você pode ter várias chaves ao mesmo tempo. Uma por ambiente ou por serviço é um bom hábito, porque dá para revogar uma sem mexer nas outras. Todas gastam do mesmo saldo de créditos.
Onde guardar
- Numa variável de ambiente ou no cofre de segredos da sua plataforma (
POPNOW_API_KEY), não no código-fonte. - Nunca num navegador, num app de celular ou em qualquer código que rode no aparelho de outra pessoa. Quem consegue ler a chave consegue gastar seus créditos. Coloque o seu próprio servidor no meio e deixe que ele chame a PopNow.
- Nem nos logs. Se você registra os cabeçalhos das requisições, remova
Authorizationantes.
Limite o que uma chave pode fazer
Cada chave pode ter os próprios limites, configurados no console da API:
| Restrição | O que faz | Erro quando bloqueia |
|---|---|---|
| Modelos permitidos | A chave só chama os modelos da lista | 40301 |
| Lista de IPs permitidos | As requisições precisam vir desses endereços ou faixas | 40302 |
| Limites de gasto | Limite diário, mensal e total da chave, em créditos | 40202 |
Por padrão, a chave não tem restrições nem limites. Dê às chaves de produção o menor escopo que ainda funcione.
As tarefas pertencem à chave que as criou
recordInfo, retry, purge, a lista de tarefas e o uso só enxergam tarefas criadas com a mesma chave. Uma tarefa criada com outra chave da sua conta responde 404, igual a uma tarefa que não existe. As gerações que você inicia no site também não aparecem para nenhuma chave. Para ver a conta inteira, use o console da API.
Rotação
Para trocar uma chave sem parar o serviço:
- Crie a chave nova.
- Faça o deploy dela em todos os lugares que usavam a antiga.
- Confira no console que o último uso da chave antiga parou de mudar.
- Revogue a chave antiga.
Se uma chave vazar
- Revogue agora no console da API. Vale a partir da próxima requisição.
- Crie uma substituta e faça o deploy.
- Veja para que ela foi usada: os logs e o uso no console mostram cada tarefa criada por ela.
- Restrinja a substituta com lista de IPs e limite de gasto.
Se aparecer algum gasto que não foi seu, fale com o suporte.
Como é uma falha
Os três problemas de autenticação retornam HTTP 401 com code: 401; quem diferencia é o msg:
msg diz | O que aconteceu | O que fazer |
|---|---|---|
| Credenciais ausentes | Nenhum cabeçalho Authorization chegou | Confira se o cabeçalho está definido e se o processo em execução carregou a variável de ambiente |
| Formato de chave não reconhecido | Chegou algo, mas não é uma chave PopNow | Verifique se começa com sk-popnow-; talvez você tenha colado outra coisa |
| Credenciais inválidas ou expiradas | A chave não existe, foi revogada ou expirou | Crie uma chave nova; tentar de novo nunca vai funcionar |
Uma chave válida também pode receber 403 — por exemplo, se o e-mail da conta ainda não foi verificado (40310). Veja Erros.