Security

Each request to LocationIQ's APIs or Map tiles needs to be authenticated with an access token.

Access Tokens

For user-facing applications such as Javascript websites or mobile apps, we recommend that you generate new access tokens on your User Dashboard. Create a separate access token for each application, label them accordingly - e.g. "my website" - and reissue these tokens frequently to prevent misuse. You can use access tokens in both public (websites, apps) and private environments (server backends).

Access Token Types

Every access token has a type that determines which endpoints it can call.

• Data access token (prefix pk.) — Calls product APIs such as Geocoding, Routing and Maps. You can add HTTP referrer and IP address restrictions, and the full token can be revealed again from the dashboard.
• Account access token (prefix sk.) — Manages account resources and cannot call data APIs. The secret is shown only once, when the token is created.

Create a data access token for each public website or app. Use account access tokens only in private, server-side environments for management tasks.

Token Scopes

A scope is a permission granted to an access token, written as group:action (for example geocoding:forward). When you create or update a token on the User Dashboard, select the scopes it should have. A token can only call endpoints that match its type and selected scopes.

• Data access tokens use scopes for the product APIs. Older data tokens created before scopes were introduced are unscoped and keep access to all data APIs.
• Account access tokens use scopes for account resources, such as balance:read. They cannot call data APIs.

The User Dashboard lists all scopes available for each token type.

Security Best Practices

Secure your access tokens to avoid abuse of your public tokens. We recommend:

• Use scopes for least privilege. Grant each token only the permissions it needs. See Token Scopes.
• Use a separate token for each app or website, and rotate tokens regularly. Rotate immediately if you notice usage spikes you do not recognize, or when the token is used in a public app.
• Store tokens safely. Treat account access tokens like passwords: they manage account resources and their secret is shown only once. Keep tokens in a password manager or secrets vault, and never commit them to source control.
• Add request restrictions where they apply. Use HTTP referrer restrictions for browser and app use, and IP address restrictions for server-side use.

IP Address restrictions

You can define a list of IPv4 addresses or subnets authorized to call our APIs or Maps with an access token. If not specified or empty, it will default to any IP address. Specify one IPv4 address or a subnet using CIDR notation (e.g. 192.168.1.0/24). For multiple IP addresses or subnets, specify one per line, upto a maximum of 5 per access token.

A few examples:

• 192.168.1.1 will restrict access to to requests from this IP
• 172.16.1.0/24 will restrict access to IPs in the range 172.16.1.0 to 172.16.1.255

Note: It may take up to 10 minutes for settings to take effect.

HTTP Referrer restrictions

You can define a list of HTTP referrers (commonly mis-spelled as referer!) authorized to call our APIs or Maps with an access token. If not specified or empty, it will default to any referrer. Referrers can be targeted by matching a prefix or a suffix using the * character. For multiple HTTP referrers, specify one pattern per line, upto a maximum of 20 per access token.

You can test patterns on the User Dashboard while viewing an access token:

By default, modern browsers use the strict-origin-when-cross-origin referrer policy. For a cross-origin request, such as an API or tile call, they send only the origin (scheme, host and port) and drop the path and query string. No referer is sent at all when a request goes from HTTPS to HTTP. Match on the host, not the path.

Patterns use shell-style wildcards, where * matches any characters, including dots and slashes. Anchor each pattern to the scheme and host, and end the host with /* so it matches the origin form browsers send plus any same-origin path. Matching ignores case, so https://Example.com/* and https://example.com/* behave identically.

For most sites, add both https://example.com/* and https://*.example.com/*, so the domain and all of its sub-domains are allowed.

Add the port if your site uses a non-default one, for example https://example.com:8443/*.

Internationalized domains

If your domain contains non-English characters, use its punycode form — the xn-- spelling. Browsers convert the host to punycode before sending the Referer header, and patterns are matched against the header exactly as it arrives, with no conversion between the two spellings. A readable pattern on its own therefore never matches real browser traffic.

The Dashboard shows you the punycode form when you type an internationalized domain, so you can copy it from there. If some of your traffic comes from non-browser clients that send the readable spelling instead, add a line for each form.