Skip to main content
Dois tipos de chave, e eles não são intercambiáveis.

​
Chaves secretas

uk_sk_…, a credencial do seu servidor. Criada no painel, mostrada uma vez, armazenada como hash SHA-256.
201
Exige api_keys:write.
key é a única vez em que o valor é legível. O que se armazena é o hash, então um dump do banco não entrega credencial funcionando — e uma chave perdida é substituída, nunca recuperada.
Uma chave nasce dentro de um ambiente e nunca sai dele. O ambiente é escolhido aqui, gravado no prefixo, e resolvido a partir da linha armazenada em toda requisição. Nada que quem chama envie depois muda isso.

​
Listando

Exige api_keys:read. Só o prefixo de exibição volta — o suficiente para reconhecer uma chave numa lista, nunca o suficiente para usar uma. last_used_at é carimbado com granularidade de minuto, best-effort: escrever a cada requisição transformaria um caminho de leitura numa escrita em linha quente.

​
Revogando

204. A linha sobrevive com revoked_at carimbado, então o rastro de auditoria de quais chaves existiram não desaparece com a chave. Chaves revogadas param de autenticar imediatamente.

​
Rotacionando

Não existe endpoint de rotação, porque rotação são duas chamadas e um deploy:
1

Crie a substituta

Mesmo ambiente, um nome que diga por que ela existe.
2

Faça o deploy

As duas chaves funcionam ao mesmo tempo — nada é exclusivo.
3

Revogue a antiga

Confira last_used_at antes: se ainda estiver se mexendo, alguma coisa ainda a está usando.

​
Chaves publicáveis

uk_pk_…, uma por ambiente, criada junto com ele. Você nunca cria nem deleta; você configura.
Devolvida em texto puro, ao contrário de todo segredo: o valor é público por definição — ele fica no HTML da sua página — e o painel é de onde um desenvolvedor copia. Uma chave publicável identifica e quase nada autoriza. Ela abre /v1/boot e os fluxos /v1/contact-auth/*, e mais nada.

​
A lista de origens permitidas

Essa lista é a fronteira de segurança de verdade de uma chave que é pública por projeto.
Exige api_keys:write. Entradas são esquema, host e opcionalmente porta. Sem path, sem query, sem fragmento — um header Origin nunca carrega nenhum deles, e uma entrada que carregasse nunca casaria com nada. Entradas malformadas respondem 400. A comparação é exata sobre a origem normalizada. Sem curingas, sem prefixos: a lista é curta, e a ambiguidade de qualquer coisa mais esperta é onde moram os bypasses.
Uma lista vazia permite qualquer origem. É o estado de começo de vida, para que os primeiros dez minutos de ninguém sejam gastos numa tela de CORS. Preencha antes de ir para produção.
Com a lista preenchida, uma requisição sem header Origin também é recusada. Navegadores sempre mandam um em cross-origin, então “sem Origin” significa “não é um navegador” — exatamente quem a lista existe para barrar. Uma origem recusada responde:
403

​
A outra proteção

O boot é limitado por chave publicável — 240 chamadas por minuto — além do limite por IP. Bots e tráfego de landing page criariam linhas de visitante para sempre, e a chave é a fronteira de tenant por onde uma enxurrada chega.

​
Qual chave vai onde

Uma chave uk_sk_ no bundle do navegador é uma chave uk_sk_ na mão de cada visitante. Entregue chaves publicáveis aos clientes; mantenha as secretas nos servidores.

​
Se uma chave vazar

1

Revogue

DELETE /v1/organization/api-keys/{id}. Ela para de funcionar na próxima requisição.
2

Crie a substituta e faça o deploy

Mesmo ambiente.
3

Se era federado, rotacione também o segredo de identidade

Um uk_is_… vazado é pior que uma chave de API vazada: ele emite sessões verificadas para qualquer id de usuário. Veja Identidade federada.
Toda credencial carrega um prefixo reconhecível justamente para que uma varredura de repositório ou um grep de log a encontre antes de outra pessoa.