N-WaysChaves de API e segurança
Cada pedido leva uma chave de API. Restrinja cada chave aos sites, aplicações ou servidores que a usam e às API de que precisa: assim, uma chave copiada não serve a mais ninguém.
Nesta página
Obter chaves. Registe-se na consola de parceiros com Google, Apple ou e-mail: a sua primeira chave é criada de imediato, e as seguintes cria-as o próprio, com as respetivas restrições; cada chave só é mostrada uma vez, quando é criada. Sem chave, as API, os mosaicos e os tipos de letra recusam os pedidos vindos de outros sites que não os do N-Ways (403).
Projetos e chaves
Um projeto agrupa as suas chaves, as API que podem chamar, as respetivas quotas e a sua utilização. Use um projeto por aplicação e por ambiente (por exemplo Aplicação do estafeta e Aplicação do estafeta, teste), para que um script de teste nunca esgote a quota da produção.
Um projeto pode ter várias chaves. Dê a cada site, aplicação e servidor a sua própria chave: poderá restringi-la ao mínimo necessário e substituí-la sem mexer nas outras.
Enviar a sua chave
Acrescente key=A_SUA_CHAVE_API ao endereço de cada pedido: chamadas aos serviços web, mosaicos e tipos de letra. O SDK Maps fá-lo por si.
GET /maps/v1/geocode?q=Wuse+2+Abuja&key=A_SUA_CHAVE_API HTTP/1.1
Host: nways.ngA partir de um servidor, pode enviá-la antes num cabeçalho, para que não apareça nos seus registos de endereços:
GET /maps/v1/geocode?q=Wuse+2+Abuja HTTP/1.1
Host: nways.ng
X-NWays-Api-Key: A_SUA_CHAVE_APIA partir de uma página web, ambas as formas funcionam: com o cabeçalho, o navegador pede primeiro autorização (um pedido CORS prévio), que o N-Ways concede; o pedido propriamente dito é depois verificado. As respostas destinadas ao seu site levam Access-Control-Allow-Origin para ele, para que a sua página as possa ler, e as recusas também, para que o seu código possa ler o motivo.
O N-Ways só responde às páginas de outros sites se enviarem uma chave que esse site tem o direito de usar. Sem chave, os dados cartográficos e as API estão reservados às aplicações N-Ways.
Restrições de aplicação
Uma restrição de aplicação indica onde uma chave pode ser usada. Cada chave tem um só tipo de restrição:
| Tipo | Para usar em | Como o N-Ways a verifica |
|---|---|---|
| Sites | Os mapas e as chamadas a partir de uma página web | O endereço da página enviado pelo navegador (o cabeçalho Referer ou Origin) |
| Aplicações Android | As chamadas a partir da sua aplicação Android | O nome do pacote da aplicação e a impressão digital SHA-1 do certificado de assinatura, nos cabeçalhos X-Android-Package e X-Android-Cert (o SDK Android envia-os por si) |
| Aplicações iOS | As chamadas a partir da sua aplicação para iPhone | O bundle ID da aplicação, no cabeçalho X-Ios-Bundle-Identifier (o SDK iOS envia-o por si) |
| Endereços IP | As chamadas a partir dos seus servidores | O endereço de onde vem o pedido |
| Nenhuma | Apenas para fazer testes | Nada. Nunca ponha em produção uma chave sem restrição. |
Endereços de sites
Indique cada site em que a chave pode ser usada. Um * substitui qualquer subdomínio no início, ou qualquer coisa no fim do caminho:
| Entrada | Autoriza | Não autoriza |
|---|---|---|
https://example.com/* | Todas as páginas de example.com | www.example.com, http://example.com |
https://*.example.com/* | www.example.com, shop.example.com | O próprio example.com: acrescente-o também |
https://example.com/track/* | As páginas em /track/ | Todo o resto do site |
http://localhost:5173/* | O seu computador, durante o desenvolvimento | Para manter apenas numa chave de desenvolvimento |
Os navegadores muitas vezes só enviam a origem do site, e não o endereço completo da página. Se uma entrada baseada num caminho não corresponder, autorize o site inteiro.
Aplicações Android e iOS
Uma entrada Android é composta pelo nome do pacote e pelo SHA-1 do certificado, separados por ponto e vírgula: com.example.rider;DA:39:A3:EE:…:07:09 (os dois pontos são opcionais). Use a impressão digital do certificado com que a loja assina a sua aplicação. Uma entrada iOS é o bundle ID: com.example.rider.
Endereços IP
Indique os endereços públicos dos seus servidores, um por linha: endereços únicos (203.0.113.7, 2001:db8::7) ou intervalos (198.51.100.0/24). Atrás de um gateway NAT ou de um balanceador de carga na cloud, indique o endereço de saída do gateway.
Restrições de API
Uma restrição de API indica o que uma chave pode chamar. Escolha apenas o que a aplicação usa:
| API | Abrange |
|---|---|
| Mapas (mosaicos) | Os estilos alojados (/maps/v1/styles/…, um carregamento de mapa cada), os mosaicos e os tipos de letra (/maps/v1/tiles/…, /maps/v1/fonts/…, e os endereços antigos /tiles/…, /fonts/…): o que os SDK Maps leem |
| Mapas estáticos | /maps/v1/staticmap |
| Geocodificação | /maps/v1/geocode, /reverse, /postcodes/…, /ghanapost/…, /pluscodes/… (e os endereços antigos /v1/geocode, /v1/reverse, /v1/postcodes/{code}, /v1/ghanapost/{code}) |
| Preenchimento automático | /maps/v1/autocomplete |
| Validação de endereços | POST /maps/v1/addresses/validate |
| Lugares | /maps/v1/places/… (e os endereços antigos /v1/search, /v1/places, /v1/places/{id}, POST /v1/places/along) |
| Percursos | POST /maps/v1/routes/compute (e os endereços antigos POST /v1/routes, POST /v1/routes/check) |
| Matriz de percursos | POST /maps/v1/routes/matrix |
| Otimização de percursos | POST /maps/v1/routes/optimize |
| Tarifas de viagem | /maps/v1/fares/estimate (e o endereço antigo /v1/fares/estimate) |
| Trânsito | /maps/v1/traffic (e o endereço antigo /v1/traffic) |
| Frota | /maps/v1/fleet/… exceto o feed de trânsito: veículos, posições, entregas, ligações de seguimento, webhooks, pacotes offline |
| Feed de trânsito | /maps/v1/fleet/traffic-feed |
| Fotografias | As fotografias dos lugares (/photos/…) |
Uma chave nunca permite a ninguém assinalar, acrescentar ou alterar seja o que for no mapa, e nunca dá acesso às contas. Só a API de Frota altera dados, e apenas os seus (os seus veículos, entregas e webhooks).
Uma chamada a uma API que a chave não tem o direito de usar recebe a resposta 403 com o motivo API_KEY_SERVICE_BLOCKED. Erros de chave
Renovar uma chave
Substitua uma chave quando possa ter havido uma fuga, quando sai alguém que a conhecia, ou uma vez por ano:
- Peça-nos para regenerar a chave, ou para criar uma nova com as mesmas restrições. Uma chave regenerada pode manter o valor antigo ativo durante 24 horas, o tempo de publicar a nova.
- Ponha a nova chave no seu site, na sua aplicação ou no seu servidor, e publique a atualização.
- Veja a utilização da chave antiga descer na consola. As aplicações nos telemóveis atualizam-se devagar: conte com dias, não com minutos.
- Desative a chave antiga. Os pedidos que a usam recebem
403 API_KEY_PAUSEDem poucos segundos, com uma mensagem a dizer que a chave está em pausa. Se algo deixar de funcionar, reative-a o tempo de corrigir. - Elimine a chave antiga quando a sua utilização tiver ficado a zero.
Se houver uma fuga de uma chave
Restrinja-a de imediato (uma chave de site aos seus sites, uma chave de servidor aos seus endereços IP) e depois renove-a como acima. Se não a puder restringir, desative-a: a sua aplicação deixará de funcionar com ela até publicar a nova chave. Avise-nos em hello@nways.ng e ajudamos a verificar a sua utilização.
Boas práticas
- Uma chave por site, aplicação e servidor, cada uma com uma restrição de aplicação e apenas as API de que precisa.
- Mantenha as chaves de servidor nos servidores. Nunca ponha uma chave restringida por endereço IP numa página web ou numa aplicação, e nunca faça commit de uma chave no seu repositório de código: leia-a de uma variável de ambiente ou do seu cofre de segredos.
- Chame os serviços web a partir do seu servidor sempre que possível. Uma página web que precisa de percursos pode pedi-los ao seu servidor, que chama o N-Ways com uma chave de servidor.
- Defina os seus próprios limites em cada chave, para que um erro ou um abuso não possa esgotar a sua quota. Quotas e limites
- Separe teste e produção, em projetos diferentes.
- Elimine o que não usa: as chaves sem uso, e as API de que uma chave já não precisa.