API (Application Programming Interface) is one of the main components of any software systems today. APIs power most of the mobile, desktop and web applications. Software companies connect their SaaS products with other applications using APIs to offer more features. APIs became so popular that some companies started selling APIs as a product to customers. APIs use a concept called API Key to identify the customer who is using their API. In this post, I will demonstrate the purpose of API Keys and how to use them.
Table of Contents
- What is API Key?
- How to use API Key?
- Where to get API Key?
- API Key Best Practices
- Disaster Recovery Plan
- FAQ
What is API Key?
As discussed in the What is API article, APIs are computer software programs without a GUI (Graphical User Interface). Most APIs are protected; to use them, one should authenticate (log in) first, similar to your online bank account that requires logging in before using the online banking service. There are multiple ways to do the authentication & authorisation in APIs; leveraging an approach known as API Key is one of the simplest yet efficient ways to do it. API Key is issued by API vendor and has the following characteristics:
- Often API Keys are an encrypted/randomly generated sequence of characters. The number of characters varies depending on the vendor, but often API keys are not shorter than 20 characters.
- It’s virtually impossible to guess an API Key due to being a long encrypted/random text.
- Your API Key is unique to you. The API vendor does not issue your API key to anyone else.
How to use API Key?
We mentioned earlier about API Key as a method of authentication and authorisation. Every time you use a protected API (sending requests to the API via code or an API Client), you must pass your API Key in your request to the API. Documentation sites for APIs often have a section called “Authentication & Authorization”, which explains how you should provide the API Key. In general, there are three main ways to pass on an API key to an API:
- Include the API Key in the URL (as a query string parameter)
- Embed as a Request Header
- Embed in Request Body
Where to get API Key?
API vendors are the authority to issue API Keys for users of an API. Depending on the vendor, you can use one of the following ways to get your API key:
- When a developer portal is provided to you by the API vendor, use the Developer Portal (sometimes called developer site) to get your API key on demand.
- Log in to your online dashboard with the vendor and look for the Settings section. Often there is an option to generate an API key on demand.
- Some vendors issue API keys manually. Request your vendor to issue an API key for you.
API Key Best Practices
API Keys are sensitive information, giving access to potentially sensitive data using an API, so it’s essential to follow the below best practices when using them.
- Always use the HTTPS protocol to use APIs and pass API Keys. Never integrate with an API that offers HTTP as it’s not secure and puts you at security risks.
- Don’t add API Keys to your code repositories like Github, Git Lab or Bitbucket.
- Use a back-end service to integrate with an external API that requires API Key. Mobile & Web developers should not use APIs that require an API Key directly but via an internal back-end service.
- Make API Key available to your code using one of the known solutions for config management.
- Make sure the log files of your servers do not have the API Keys.
- Check with your team about the time it takes to update an API key in your running system. You should be able to easily update the API key to a new one in case of API Key leak emergencies. (More in disaster recovery plan)
- Practice generating a new API key regularly and using the new key for integration.
- Exchanging API keys via email and messaging apps like Slack is not safe. Consider using a tool that is built for transferring sensitive information.
Disaster Recovery Plan
Disaster, in the context of API keys, means unauthorised access to your API keys. The unauthorised access happens for many reasons, but it occurs primarily because you or someone from your team has accidentally shared the API key with someone else or made the API key accessible to the public. It’s important to be ready for situations like this.
Below is a gist of our disaster recovery plan at Testfully and something for you to consider:
- Make it easy and straightforward for the authorised people in your organisation to reset API keys in the event of a disaster.
- Make sure the process of rolling out a new API key to your running system is straightforward and fast. In the event of a disaster, you want to quickly update your API key with minimum downtime for your service.
- Don’t wait for a disaster to exercise your plan. Exercise your plan regularly to make sure your system is capable of handling API key updates.
FAQ
What is API Key?
API keys are encrypted/randomly generated sequence of characters generated by an API vendor. API Keys are used to authorising requests to an API.
What is Sandbox API Key?
Some APIs provide a sandbox version of their service, a playground for developers to start using an API without impacting customer data. Sandbox API Key is an API key used to access a sandbox API.
What API key should be used for testing purposes?
It’s best practice to have dedicated API keys for testing and usage in production to minimise the risk of data loss, bugs or undesired behaviour. Most API vendors offer sandbox environments to test APIs, and we recommend leveraging sandbox APIs for testing purposes.
What disaster recovery plan means for an API Key?
Disaster, as far as it’s related to an API key, means your API Key is available to unauthorised people. It’s essential to be able to quickly revoke an API key as soon as it’s leaked. Moreover, you need to update your system ASAP with a new API key to minimise system interruption.