Como limitar uma chave de API a um único projeto

Uma chave de API pode ser associada a um único projeto Cryptanio. Vamos considerar um processo de conferência de encomendas que precisa de ler as faturas de uma loja online, sem obter dados dos outros projetos da conta. Este processo precisa de uma chave separada: a associação ao projeto define o âmbito dos dados, enquanto as permissões e as secções da API definem as operações permitidas.

Nem o nome da chave nem o número do projeto na sua aplicação limitam o acesso por si só. A restrição tem de ficar guardada na política da chave. Este acesso aplica-se à API pública v1; a chave não é uma palavra-passe para entrar na conta.

1. Prepare o projeto e as permissões

Precisa de permissões de proprietário ou administrador da conta e de um projeto ativo existente com o serviço «Pagamentos». Primeiro, confirme que reconhece o nome e a finalidade do projeto: escolher o projeto errado pode gerar uma chave válida com um âmbito de acesso inadequado.

Abra «API chaves». No formulário «Criar chave de API», preencha «Rótulo», por exemplo com «Conferência da loja». Um nome próprio ajuda a distinguir os processos do servidor, mas a proteção efetiva é definida nos campos seguintes.

2. Escolha o modo e o projeto concreto

Para ler faturas reais, selecione «Produção» no campo «Modo». A chave deve corresponder ao modo dos dados pedidos pelo seu servidor.

No campo «Projeto», selecione o projeto pretendido em vez de «Todos os projetos». A interface apresenta uma indicação sobre a limitação ao serviço do projeto selecionado. A associação ao projeto e o acesso ao serviço aplicam-se em conjunto: a chave não ativa o serviço nem amplia as suas capacidades por si só.

3. Permita apenas a leitura de faturas

No campo «Acesso», selecione «Apenas para leitura». Em «API seções», mantenha «Facturas» e desmarque as restantes opções se o processo não precisar delas. Para uma conferência normal do estado de uma fatura, não é necessário gerir endereços, webhooks ou simulações.

Se outro servidor precisar de criar faturas, necessitará de «Ler e escrever» e da secção correspondente. Atribua-lhe uma chave separada com uma finalidade clara, sem ampliar desnecessariamente as permissões do processo de conferência. O acesso de escrita atua dentro das secções selecionadas e não abre toda a API.

4. Configure os IPs e a validade

Em «Endereços IP permitidos», indique os IPs públicos de saída do seu servidor ou os intervalos CIDR necessários, um por linha. É necessário o endereço de origem com que o pedido chega à API, e não o IP do comprador. Se usar alojamento ou um proxy, confirme o endereço de saída efetivo.

Um campo vazio permite qualquer IP. Se o servidor utilizar vários endereços de saída, tenha-os em conta na configuração; caso contrário, uma chave correta pode ser recusada na verificação. A restrição por IP complementa a escolha do projeto e das secções, sem as substituir.

Se necessário, defina «Expirar». A data escolhida é válida até ao fim desse dia em UTC. Faça-a coincidir com o período de funcionamento da integração: uma chave expirada não indica que o cliente não pagou.

5. Crie a chave e guarde o segredo

Clique em «Criar a chave» e conclua a confirmação de segurança, se a interface a solicitar. Copie o segredo da janela apresentada e guarde-o no servidor do processo de conferência. Não o coloque no JavaScript do cliente, numa ligação de pagamento, na correspondência com o comprador ou num registo público.

Depois de fechar a janela, não conte com a recuperação do segredo a partir da lista: esta mostra apenas uma identificação abreviada da chave. Verifique «Fronteira», o projeto, as secções disponíveis, a validade e o estado. Se um programador precisar de acesso, forneça-o através de um local seguro apropriado, em vez de publicar a chave juntamente com as instruções.

6. Verifique o acesso permitido e o acesso proibido

A partir de um servidor com um IP permitido, leia uma fatura conhecida deste projeto. Abaixo está um exemplo de leitura do catálogo de API; use o seu próprio ID de fatura e a chave criada:

#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_RESOURCE_ID:?Set CRYPTANIO_RESOURCE_ID}"
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
urlencode() {
  local LC_ALL=C text="$1" char index
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in [a-zA-Z0-9.~_-]) printf '%s' "$char" ;; *) printf '%%%02X' "'$char" ;; esac
  done
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request GET \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  "https://api.cryptanio.com/v1/invoices/$(urlencode "$CRYPTANIO_RESOURCE_ID")" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

Transferir exemplo

Em seguida, verifique o limite de acesso com uma fatura conhecida de outro projeto seu: os respetivos dados não devem ser devolvidos. As listas também devem ficar limitadas ao projeto selecionado. Para esta chave, a criação e a alteração de faturas são proibidas, mesmo que a secção «Facturas» esteja ativada. A organização das verificações seguintes é explicada no guia para verificar pagamentos através da API.

Se um pedido falhar, verifique o projeto, o modo, o IP, a validade e as permissões. Não conclua que falta um pagamento com base num único erro de acesso nem substitua a chave limitada por uma chave geral da conta. O pagamento é avaliado pelo estado da fatura.

Como ajustar o acesso mais tarde

Numa chave existente, clique em «Acesso», altere o projeto, as secções, os IPs ou a validade e selecione «Salvar acesso». O modo é escolhido ao criar a chave. «Renovar» muda o segredo e desativa imediatamente o anterior; «Revogar» termina a utilização da chave. Antes de a renovar, prepare a atualização dos clientes no servidor para que a conferência das encomendas não pare.