Authentication
Dois mecanismos fáceis de confundir
Uma chave de API diz que sistema está a chamar. Uma credencial verificável diz que nível um terceiro tem direito a ler. Tratar a segunda como uma variante da primeira é o erro mais caro de uma integração de passaporte.
- Sistema
- Bearer
- Delimitado por
- Ambiente + capacidade
- Terceiros
- Credenciais W3C
Definition
Como se faz a autenticação na API do passaporte?
Os seus sistemas apresentam, por HTTPS, uma chave portadora de âmbito limitado, emitida por ambiente e por capacidade. Os terceiros que leem níveis restritos do passaporte não usam chaves de todo: apresentam uma credencial verificável W3C emitida por uma parte em que a política de acesso confia, e o resolvedor devolve o nível a que essa credencial lhes dá direito.
The separation matters because the two have different lifecycles. A key belongs to your integration and rotates on your schedule; a credential belongs to a recycler or an authority and is revoked when their permit lapses, not when your contract does.
Pedidos
Apresentar uma chave
curl https://api.circuleid.com/v1/passports/01/09506000134352 \
-H "Authorization: Bearer $CIRCULEID_API_KEY"
# Scope errors are explicit rather than a bare 403:
# {
# "error": "insufficient_scope",
# "required": "passports:read:restricted",
# "granted": ["passports:read:public", "events:write"]
# }Comparação
Chaves e credenciais lado a lado
| API key | Verifiable credential | |
|---|---|---|
| Authenticates | Your systems | A third party reading a passport |
| Issued by | CirculeID, to your organisation | A party the access policy trusts |
| Scoped by | Environment and capability | What the credential asserts |
| Revoked when | You rotate or a key leaks | A permit or accreditation lapses |
| Verified by | Us, on each request | Anyone, cryptographically |
| Lives in | Your secret manager | The holder’s own wallet or system |
Práticas
O que recomendamos
Uma chave por serviço
Assim, uma fuga tem um raio de impacto que consegue descrever numa frase.
Âmbitos de privilégio mínimo
Um pipeline de emissão nunca precisa de acesso de leitura aos níveis restritos.
Separação de ambientes
Por construção, uma chave de sandbox não consegue alcançar passaportes de produção.
Rotação com sobreposição
Ambas as chaves são válidas durante a mudança, pelo que a rotação não se torna uma corrida de implantação.
De vida curta sempre que possível
Uma validade nas chaves usadas por cargas efémeras limita durante quanto tempo uma fuga importa.
Verifique antes de presumir
O registo mostra o que uma chave fez enquanto era válida — a base para avaliar a exposição.
Respostas
Perguntas frequentes
Qual é aqui a diferença entre uma chave de API e uma credencial?
Uma chave de API autentica os seus sistemas perante a CirculeID e está limitada ao que a sua organização pode fazer. Uma credencial verificável autentica um terceiro — reciclador, reparador, autoridade — perante um passaporte e determina que nível recebe. As chaves somos nós que as emitimos; as credenciais vêm de quem a política de acesso reconhecer.
Como devem as chaves ser delimitadas?
De forma restrita e por serviço. Um pipeline de emissão precisa de acesso de escrita aos passaportes e de mais nada; uma loja precisa de acesso de leitura ao nível público e de mais nada. Delimitar por capacidade significa que uma chave comprometida num serviço não expõe dados restritos de outro.
As chaves de sandbox e de produção são intercambiáveis?
Não, deliberadamente. As chaves transportam o seu ambiente, pelo que uma chave de sandbox não pode tocar passaportes de produção e uma chave de produção não pode ser usada por engano num ambiente de teste. Os passaportes são artefactos públicos de longa duração; uma emissão acidental em produção não é coisa que se apague discretamente.
Como é tratada a rotação de chaves?
As chaves podem sobrepor-se: emita a nova, implante-a e depois revogue a antiga, com ambas válidas no intervalo. Rodar sem janela de sobreposição é uma corrida de implantação, e é assim que as organizações acabam por nunca rodar chaves.
O que acontece se uma chave for exposta?
Revogue-a de imediato; a revogação produz efeito no pedido seguinte e não no fim de uma cache. O registo de auditoria mostra o que essa chave fez enquanto era válida, que é o que precisa para avaliar a exposição — e a razão pela qual delimitar bem as chaves torna essa avaliação curta.
Next step
Obter uma chave de sandbox
Limitada a uma única capacidade, num ambiente que não pode tocar em nada real.