June 2, 2023 | 5 Min
What Is An API Key and Why Do You Need Them?
In part one of our API blog series, we explored how APIs work. Some of our APIs use API keys. In this article, we’ll explore what an API key is and how to work with them. We’ll look at how the Fresh API uses an API key and why.
What is an API key?
An API key identifies and authenticates applications to access systems.
We are used to logging in to systems. We provide credentials to prove who we are. It’s like a handshake between you and the system. You input your username and password and if those details match what’s in the system, you’re allowed in to use it. After providing your credentials once, the system gives you a “ticket“ or a “token“ for your session. It proves that you’ve already done the credentials handshake. Now, you don’t need to keep sharing your password every time you ask the system to do something.
This approach works well for people. What about applications, rather than people, talking to systems?
Applications often interact with systems through an API (see part one of our ‘What is an API?’ blog). Instead of a password, they use something called an API key. This is like a unique passcode for a specific application, not a person. The API key identifies and authenticates that application to access the API.
An API key is typically a random string:
1abc123adOxTBqHRXBXyDoYlPxIDREBcuzsWHBGoN
The key is held by the system and securely shared with the developers building the application.
How to use an API key
In web-based APIs, API keys are sent in the request to the server. They might need to be placed in the query string or as a request header. Here’s an example of sending our example demo API key in the request header:
1GET /resource HTTP/1.1 2X-API-Key: abc123adOxTBqHRXBXyDoYlPxIDREBcuzsWHBGoN
APIs that provide an SDK make this easier. We’ll see how that’s done by looking at our Fresh API as a case study, below.
How do I get an API key?
Getting an API key depends on who provides it. Here are some ways API keys are given out:
Self-service registration - This means you can visit the organization’s website and sign up to get your API key instantly. They’ll give you the key right away, so you can start using their services.
Application process - This means you have to apply for an API key by providing some information. They want to know how you plan to use their API. You might have to explain your project or give details about your website or app. They’ll review your application and decide whether to give you the API key.
Support team - The organization might distribute API keys through their support team. So, you’ll have to reach out to their support team, either by email or through a contact form on their website. You can ask them for an API key, and they’ll assist you with the process. This is often used in an enterprise setting where there might be a commercial aspect.
The key will typically be given to you in a secure way.
Why do you need an API key?
APIs choose to require API keys for a variety of reasons:
APIs often want to block anonymous or unauthorized traffic, ensuring that only authorized users can access their services.
API keys help control the volume of traffic, preventing overwhelming volumes of requests and ensuring fair usage.
API keys help with analytics and insights, allowing API owners to improve their services and tailor them to the needs of their users.
At Amplience, we use API keys for all of these reasons.
Case study: the Fresh API
A great example of how API keys are used is our Fresh API. This API is designed for use with static-site-generators (SSGs); applications that build websites ahead of time.
We issue API keys for use with the Fresh API via our support team. The API key lets us identify and authorize the application to use the unique features of the Fresh API. Developers will typically use our dc-delivery-sdk-js library to work with the API. This SDK makes it easy to configure the API key:
1js 2const client = new ampDynamicContent.ContentClient({ 3hubName: 'myhub', 4apiKey: 'abc123adOxTBqHRXBXyDoYlPxIDREBcuzsWHBGoN', 5});
All of the details on how the API key is used is managed by the SDK. Now that the client is configured, the API will be able to retrieve content:
1js 2const client = new ContentClient({ 3hubName: 'myhub', 4apiKey: 'abc123adOxTBqHRXBXyDoYlPxIDREBcuzsWHBGoN', 5});const slot = 'homepage-banner-slot'; 6client .getContentItemByKey(slot) 7.then((content) => { 8console.log(content.body); 9}) 10.catch((error) => { 11console.log('content not found', error); 12});
Under the hood, the SDK sends the API key as a request header, exactly like the example above.
In this way, our Fresh API can identify its users, ensures fair use, and lets our Product team analyze its use to help drive new features.