Originally published June 2023. Updated November 2026 to add what an API is, how API keys differ from access tokens, how to keep keys secure, and corrected code.
An API key is a unique code that identifies an application, not a person, when it calls an API. The API checks the key before it responds, which lets the provider block unknown traffic, control volume and see how the API is used. Below, we explain what an API is, then how API keys work.
Key takeaways
An API (application programming interface) is how one piece of software asks another for data or actions.
An API key identifies the application making the request, much like a password identifies a person.
Providers use API keys to block anonymous traffic, manage volume and understand usage.
Access tokens are short-lived and scoped. Amplience’s Content Management API uses an API key and secret to get a token that expires after a few minutes.
Keep API keys out of browser code and source control, store them as environment variables, and rotate them if they leak.
What is an API?
API stands for application programming interface. It defines how one piece of software can ask another for data or actions, without needing to know how the other system works inside.
Web APIs come in a few main styles:
HTTP APIs send simple requests to web addresses and get data back. They’re lightweight and fast, which suits high-volume content delivery.
REST APIs organize everything as resources with links between them, so a client can discover what it can do next.
GraphQL APIs let the client ask for exactly the fields it needs in one request, which avoids fetching too much or too little.
Amplience picks the style to suit the job. The Amplience Content Management API is a REST API, and content delivery uses lightweight HTTP APIs built for speed. Those APIs are what make Amplience CMS a headless CMS: any website, app or device can request the same content.
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.
Logins work well for people. What about applications, rather than people, talking to systems?
Applications often interact with systems through an API (see above). 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.
Amplience provides API keys at the start of a project or through Amplience support. 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.
What’s the difference between an API key and an access token?
An API key is usually long-lived and identifies the application. An access token is short-lived, can be limited to specific permissions, and expires on its own, which makes a leaked token less dangerous.
Many APIs use both. The Amplience Content Management API uses OAuth2: your application sends its API key and secret to the Amplience authorization service and gets back an access token, which it includes in every request. The token expires after a set period, generally 300 seconds, and the flow is meant for server-to-server integrations only.
How do you keep API keys secure?
Treat an API key like a password:
Keep it on the server. Don’t put keys in browser code or mobile apps, where anyone can read them.
Keep it out of source control. Store keys as environment variables or in a secrets manager.
Use one key per project and environment, so you can see where traffic comes from and revoke one without breaking the rest.
Rotate keys regularly, and immediately if one leaks.
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. Because the Fresh API runs at build time on a server, the API key never reaches the shopper’s browser.
The SDK handles how the API key is used. Once the client is configured, it can retrieve content:
1 const { ContentClient } = require('dc-delivery-sdk-js'); 2 3// Keep the key out of your code by reading it from an environment variable 4const client = new ContentClient({ 5 hubName: 'myhub', 6 apiKey: process.env.AMPLIENCE_FRESH_API_KEY, 7}); 8 9client 10 .getContentItemByKey('homepage-banner-slot') 11 .then((content) => { 12 console.log(content.body); 13 }) 14 .catch((error) => { 15 console.log('content not found', error); 16 });
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.