Skip to content

Authentication

Let's get you connected! The first thing you'll want to know is how to authenticate your requests. While you're here, we also encourage you to at least skim the documentation on limits.

Authentication

Local development

You can get started developing locally without any special effort or cost. If your application is running via a development web server accessed via localhost or 127.0.0.1, we'll treat your requests as coming from a free plan. Note that this is designed for convenience of development on a single machine, and is rate limited accordingly. If you start receiving HTTP 429 responses, please sign up for an account (it's free!) and use an API key.

Domain-based authentication

Domain-based authentication is the easiest form of authentication for production web apps. No additional application code is required, and you don't need to worry about anyone scraping your API keys. We recommend this for most browser-based applications.

  1. Sign in to the client dashboard.
  2. Click "Manage Properties."
  3. Under "Authentication Configuration," click the button to add your domain.
Getting a 401 Unauthorized response or seeing a Stamen warning tile?

Domain authentication usually "just works" but sometimes it doesn't. These are a few common issues related domain authentication.

  • Referrer-Policy is set to no-referrer. Some platforms, such as Azure Static Web Apps, do this by default. Relaxing this header to something like strict-origin-when-cross-origin (if your site uses HTTPS; origin-when-cross-origin if using HTTP) will let us authenticate your requests while preserving privacy.
  • The Origin or Referer domain is a nested subdomain. If your site is hosted on a.b.example.com, set the subdomain to a and the domain to b.example.com as shown in the screenshot below:

Image illustrating a correctly filled out nested subdomain form

API keys

You will need to include an API key with each request that is made outside a web browser.

Generating and Revoking API keys

You can manage your API keys in the client dashboard.

  1. Sign in to the client dashboard. (If you don't have an account yet, sign up for free; no credit card required!)
  2. Click "Manage Properties."
  3. If you have more than one property (ex: for several websites or apps), make sure you have selected the correct property from the dropdown at the top of the page.
  4. Under "Authentication Configuration," you can generate, view or revoke your API key.

Screenshot of API key management in the client dashboard when no key exists

Video: How to generate your API key

Security

Please take care not to expose your API key. You generally should use domain-based authentication for web browser applications. Use API keys only for requests coming from outside a web browser or for local development when you need to make requests in excess of the rate limit for keyless access.

Tip

Securing your API keys is your responsibility, and requires special care whenever an application is available to end users outside your organization. This has always been tricky, but we can offer some general best practices:

  1. Avoid shipping API keys in an app binary when possible. For example, an iOS you can take advantage of on-demand resources to separate this from the IPA download. You could also host a similar key retrieval mechanism on your own servers; just be sure to be careful about access control!
  2. Ensure that any long-term storage of API keys uses the platform's hardware-secured APIs for credential storage.

Using your API key

You can use API keys in two ways. The simplest is to add a query string parameter api_key=YOUR-API-KEY to your request URL. Note that you can add an API key query parameter to vector stylesheet URLs (which don't require authentication to access), and the provided key will be embedded in the stylesheet. You'll need to authenticate requests from mobile apps and certain websites (ex: intranet accessed via IP) this way.

You can alternately add an Authorization header with the value Stadia-Auth YOUR-API-KEY.

Examples

https://api.stadiamaps.com/tz/lookup/v1/?api_key=YOUR-API-KEY

Authorization: Stadia-Auth YOUR-API-KEY