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).

If you need help creating access tokens, watch this video:

Security Best Practices

As a best practice, you need to secure your API Access Tokens. We recommend use some or all of the options below to avoid abuse of your public access tokens.

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 10 per access token.

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

A few examples:

• *example.com* - allow access for the full domain and sub-domains of example.com

  • These referrers match the pattern:

    • https://example.com
    • http://www1.example.com/

  • These referrers do not match the pattern:

    • https://example.org - .org does not match
    • https://ExamPLE.com - because patterns are case-sensitive

• https://example.com/* will restrict access to all referrers starting with https://example.com/.

  • These referrers match the pattern:

    • https://example.com/abc
    • https://example.com/

  • These referrers do not match the pattern:

    • https://www.example.com/ - because www. does not match
    • https://example.com - no trailing / like the pattern requires
    • http://example.com - http: does not match

• *.example.com/ - will restrict access to all referrers ending with .example.com/.

  • These referrers match the pattern:

    • https://abc.example.com/
    • http://www.example.com/

  • These referrers do not match the pattern:

    • http://www.example.com - no trailing / like the pattern requires
    • https://ExamPLE.com - because patterns are case-sensitive.
    • http://example.com - example does not have the leading .

The referrer is an HTTP header that is sent by browsers and like all HTTP headers, it can be spoofed. To limit misuse when using access tokens on a public site, we recommend frequent access token rotation along with referrer restrictions.

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.

📘

Do not use IP restrictions for browser-based use-cases such as showing Maps or an Autocomplete widget. This is because these requests originate from your end user's IP address and not your server's IP. Your user's IP will not pass the IP restriction pattern. Use IP restrictions for API calls that originate from your server with a fixed IP / range.