This guide includes the following sections:


Introduction

API Key authentication allows you to consume Nearmap imagery in an application without having to provide your Nearmap username and password as authentication credentials. Instead you include an API Key – a unique long string associated with a particular user on your Nearmap account – and then include that API Key in all requests to Nearmap endpoints, typically by appending it to a URL.

Before you can create an API key, your Nearmap Admin needs to have created an API App for the key to live under. 


We recommend you read this article to understand how API Apps and API keys works. If you already can see an API App and just want to create your own API key, read this article: Managing API Keys.





Management

You manage API Keys using a simple user interface within your Nearmap profile. No API call is needed to create an API Key.

Validity

An API Key is valid until you delete it.

You do not have to regularly refresh it.

Usage

API Key authentication works for both desktop applications and custom web applications. If your application supports using map content via any of the supported Nearmap interfaces, including WMSTile API and Image API, you should be able to integrate Nearmap imagery with minimal configuration using an API Key.
Your own API key (the key you create and use) incurs usage whenever you use it in a third party application.

Configuration

You can configure an API Key so that it can only be used from a restricted set of IP addresses or applications. See Managing API Applications for details.

Restrictions

By design, you cannot use an API Key to log into the Nearmap MapBrowser and the Customer Portal web application. Use your Nearmap username and password to log into both MapBrowser and Account Management.



Organising Your Integrations

There are two key components to Nearmap API Key authentication:

API Applications

  • These allow you to organise your Nearmap integrations, and to set different access restrictions for different integrations.
  • You can have as many API Applications as you need on your Nearmap account.
  • You must be a Nearmap administrator to create and manage API Applications. 
  • Only Nearmap Admin can create API Apps. If you don't have an API App and you're not a Nearmap Administrator, get your Administrator to create one for you.

API Keys

  • Every user on a Nearmap account can create one API Key for each API Application on that account.
  • Usage accrued by an integration that uses an API Key will be a recorded against the user who owns that API Key.


Creating your API Key

This article steps you through creating your API Key: Managing API Keys.


More About API Key Authentication in Nearmap