Chaves de API
Qual chave faz o quê, onde cada uma pertence, e como a plataforma decide.
Uma chave identifica a sua aplicação para a plataforma. Ela não é a credencial do usuário — o usuário é identificado pelo token de sessão, que viaja separado. A maioria das chamadas precisa dos dois, e eles respondem perguntas diferentes: a chave diz qual projeto e ambiente é este, a sessão diz quem está perguntando.
A chave viaja no header x-platform-key em toda requisição. Um SDK coloca
ela por você quando você constrói um client; se você está chamando a API direto,
ou escrevendo um client para uma linguagem que ainda não publicamos, esse header
é o contrato inteiro.
Tipos
O tipo é inferido do prefixo, antes de qualquer outra coisa acontecer.
pk-publicávelNavegadores, apps mobile, qualquer coisa que você distribui. Seguro embutir.
sk-secretaSó servidor a servidor. É uma capacidade em si mesma.
O corpo depois do prefixo tem 32 caracteres seguros para URL, gerados a partir de 24 bytes aleatórios.
Uma chave por ambiente
Chaves pertencem a um ambiente, não a um projeto. Uma pk- de desenvolvimento
não alcança dados de produção — não é questão de permissão, é outro armazenamento.
Veja Fundamentos.
Chaves publicáveis
Uma chave publicável identifica a aplicação. Ela não autoriza o usuário.
É essa distinção que torna seguro distribuí-la num bundle: possuir uma não concede nada por si só. Toda chamada que toca dados de usuário ainda precisa da sessão dele, e o que essa sessão pode fazer é decidido pelos grants.
GET /session
x-platform-key: pk-…
Authorization: Bearer <token de sessão>Chaves secretas
Uma chave secreta alcança a superfície administrativa — administração de usuários, papéis e grants, envio de mensagens. Não há usuário por trás dela, então não há nada contra o que verificá-la além da própria chave.
POST /admin/users
x-platform-key: sk-…Leia do ambiente, nunca do repositório, e nunca de código que vai para o bundle de um client.
Mostrada uma vez
Uma chave secreta é guardada como hash. Só as publicáveis ficam numa forma
que a plataforma consegue decifrar, o que significa que uma sk- que você não
copiou na criação está perdida — o console mostra os últimos quatro caracteres e
nada mais.
Coloque no ambiente na hora da criação, ou crie outra.
Como a plataforma decide
Todo endpoint declara quais tipos de chave aceita. A verificação roda nesta ordem:
- O prefixo é lido.
pk-ousk-— o tipo é inferido da própria chave, não do que você alega. - O tipo é casado com a lista do endpoint. Um tipo fora dela é rejeitado imediatamente, antes mesmo de a chave ser validada. Uma chave publicável enviada para uma rota de admin falha aqui.
- A chave é validada contra o ambiente.
Um endpoint que não declara nada não aceita nada, então uma rota administrativa nova nasce fechada em vez de aberta até alguém lembrar de fechá-la.
Um conjunto pequeno de endpoints declara que não precisa de chave alguma — os que precisam funcionar antes de a aplicação ser identificada.
Expiração e substituição
Uma chave pode ter expiração, depois da qual ela para de validar.
Não existe rotação embutida. Para substituir uma chave você cria a nova, move o tráfego, e depois apaga a antiga — as duas valem no intervalo, então não há janela em que nenhuma funcione. A ordem importa: apagar primeiro quebra tudo que ainda estiver usando.
Rotacione por ambiente, não globalmente. Trocar uma chave secreta de produção não tem nada a ver com a que a sua CI usa, e fazer as duas juntas transforma um incidente em dois.
No SDK JavaScript
A chave que você passa decide qual client você recebe, e portanto quais namespaces existem:
createClient(url, 'pk-…'); // só auth
createServerClient(url, 'sk-…'); // auth + comms + adminVeja Clients. Outros SDKs traçam a mesma linha — o tipo de chave é uma regra da plataforma, não do JavaScript.