Protect your API key

Background

Your OpenCage geocoding API key is a 30 character alphanumeric string. You set it as the value of the key parameter, one of the two required parameters, on every request to the OpenCage geocoding API.

Once you log in you will find your API key in your account dashboard.

General points

Disabling your geocoding API key(s)

In your account dashboard you can disable your API key at any time and replace it with a new API key.
Please see our guide to replacing your API key.

Multiple API keys per account

Free trial and one-time plan accounts are limited to one active key at a time, subscription customers can have multiple keys. These can be created (or disabled) anytime in your account dashboard.

Can I publish my API key publicly?

We advise you not to do this as then anyone who looks in the source code can grab your geocoding API key.

A better approach is to have your client-side code call server-side code (be it hosted on your servers, or on a serverless framework (we have tutorials for many), this way you have full control over what is happening and your key is not publicly visible.

What if someone "steals" my geocoding API key?

If you believe someone is abusing your API key please get in touch with us.

One worry that potential clients sometimes raise is that someone will get their API key and start using it heavily and they will face a large and unexpected bill. Fear not - that can't happen because of how our pricing works. Subscription customers buy a month (or year) in advance, and there is no usage based charging. If we see an explosion of usage we email you and ask if it is expected and the source is known. If yes, and it will be ongoing, we ask you to move to a higher pricing tier in the future, but this never happens as a surprise. If no, we can help you work out what is going on.

Preventing abuse

Please do NOT put your API key in a public repository on GitHub

Please do not check your key into GitHub or other public version control service. A better approach is to have your code access the API key via an environment variable or command line parameter that is set at the time the software is run. The best way to do this will depend on exactly which platform you are running on and which technology you are using, but we strongly encourage you to spend a few minutes learning whatever the best practices are for your stack.

Here are some examples of software for managing API keys

You can use automated code quality tools like Datatree to define a policy of not allowing secret credentials into source code with automated checks at each code commit. Finally, please see this excellent post about how to handle API keys and similar secrets on the command line.

IP restriction

Subscription customers can add IP address restriction to their API keys. Any API request that comes from a non-allowed IP address will then receive a 403 - Forbidden status code as the response for all requests. This can be configured in your account dashboard.

We do not support IP restriction for free trial or one-time purchase accounts, as, by definition, both are meant for short-term use.

Cross-origin resource sharing (CORS) HTTP header

By default all API responses return the HTTP header access-control-allow-origin: *. which specifies that all cross-origin requests are allowed. Paying customers can define a domain to limit cross-origin requests to in their account dashboards. Please see the details in the API documentation.

General security advice

Securing your account

You can set up two-factor authentication on your account (see the blog post where we announced this and we recommend you do so.),

We should also note that we (OpenCage) have no access to your payment details, that is all stored in Stripe, our payment processor.

Further reading

Our Security Policy and Security Bounty program

Please see our security policy. If you would like to report a security issue please see the details of our security bounty program.

Questions or concerns?

Please contact us if anything is unclear. We are here to help.

Start your free trial

2,500 geocoding API requests per day.

No credit card required.