Search by Algolia
How personalization boosts customer engagement
e-commerce

How personalization boosts customer engagement

You land on your favorite retailer’s website, where everything seems to be attractively arranged just for you. Your favorite ...

Jon Silvers

Director, Digital Marketing

What is retail analytics and how can it inform your data-driven ecommerce merchandising strategy?
e-commerce

What is retail analytics and how can it inform your data-driven ecommerce merchandising strategy?

There is such tremendous activity both on and off of retailer websites today that it would be impossible to make ...

Catherine Dee

Search and Discovery writer

8 ways to use merchandising data to boost your online store ROI
e-commerce

8 ways to use merchandising data to boost your online store ROI

New year, new goals. Sounds positive, but looking at your sales data, your revenue and profit aren’t so hot ...

John Stewart

VP, Corporate Communications and Brand

Algolia DocSearch + Astro Starlight
engineering

Algolia DocSearch + Astro Starlight

What is Astro Starlight? If you're building a documentation site, your content needs to be easy to write and ...

Jaden Baptista

Technical Writer

What role does AI play in recommendation systems and engines?
ai

What role does AI play in recommendation systems and engines?

You put that in your cart. How about this cool thing to go with it? You liked that? Here are ...

Catherine Dee

Search and Discovery writer

How AI can help improve your user experience
ux

How AI can help improve your user experience

They say you get one chance to make a great first impression. With visual design on ecommerce web pages, this ...

Jon Silvers

Director, Digital Marketing

Keeping your Algolia search index up to date
product

Keeping your Algolia search index up to date

When creating your initial Algolia index, you may seed the index with an initial set of data. This is convenient ...

Jaden Baptista

Technical Writer

Merchandising in the AI era
e-commerce

Merchandising in the AI era

For merchandisers, every website visit is an opportunity to promote products to potential buyers. In the era of AI, incorporating ...

Tariq Khan

Director of Content Marketing

Debunking the most common AI myths
ai

Debunking the most common AI myths

ARTIFICIAL INTELLIGENCE CAN’T BE TRUSTED, shouts the headline on your social media newsfeed. Is that really true, or is ...

Vincent Caruana

Senior Digital Marketing Manager, SEO

How AI can benefit the retail industry
ai

How AI can benefit the retail industry

Artificial intelligence is on a roll. It’s strengthening healthcare diagnostics, taking on office grunt work, helping banks combat fraud ...

Catherine Dee

Search and Discovery writer

How ecommerce AI is reshaping business
e-commerce

How ecommerce AI is reshaping business

Like other modern phenomena such as social media, artificial intelligence has landed on the ecommerce industry scene with a giant ...

Vincent Caruana

Senior Digital Marketing Manager, SEO

AI-driven smart merchandising: what it is and why your ecommerce store needs it
ai

AI-driven smart merchandising: what it is and why your ecommerce store needs it

Do you dream of having your own personal online shopper? Someone familiar and fun who pops up every time you ...

Catherine Dee

Search and Discovery writer

NRF 2024: A cocktail of inspiration and innovation
e-commerce

NRF 2024: A cocktail of inspiration and innovation

Retail’s big show, NRF 2024, once again brought together a wide spectrum of practitioners focused on innovation and transformation ...

Reshma Iyer

Director of Product Marketing, Ecommerce

How AI-powered personalization is transforming the user and customer experience
ai

How AI-powered personalization is transforming the user and customer experience

In a world of so many overwhelming choices for consumers, how can you best engage with the shoppers who visit ...

Vincent Caruana

Senior Digital Marketing Manager, SEO

Unveiling the future: Algolia’s AI revolution at NRF Retail Big Show
algolia

Unveiling the future: Algolia’s AI revolution at NRF Retail Big Show

Get ready for an exhilarating journey into the future of retail as Algolia takes center stage at the NRF Retail ...

John Stewart

VP Corporate Marketing

How to master personalization with AI
ai

How to master personalization with AI

Picture ecommerce in its early days: businesses were just beginning to discover the power of personalized marketing. They’d divide ...

Ciprian Borodescu

AI Product Manager | On a mission to help people succeed through the use of AI

5 best practices for nailing the ecommerce virtual assistant user experience
ai

5 best practices for nailing the ecommerce virtual assistant user experience

“Hello there, how can I help you today?”, asks the virtual shopping assistant in the lower right-hand corner ...

Vincent Caruana

Senior Digital Marketing Manager, SEO

Add InstantSearch and Autocomplete to your search experience in just 5 minutes
product

Add InstantSearch and Autocomplete to your search experience in just 5 minutes

A good starting point for building a comprehensive search experience is a straightforward app template. When crafting your application’s ...

Imogen Lovera

Senior Product Manager

Looking for something?

facebookfacebooklinkedinlinkedintwittertwittermailmail

We’ll start with the standard definition:

An API key is a string of characters used to identify and authenticate an application or user who requests the service of an API (application programming interface). 

In this article, we break down this definition for the curious folk (tech or non-tech) who want to know the inside story of what an API key is and does, and how it works. 

An API key is the secret code that gets you inside

Identification and authentication

An API key is the standard security mechanism for any application that provides a service to other applications. 

While they are not the only method (APIs can use JWT, which we wrote about here: API keys vs JWT auth), API keys are the most-often used method of securing an API.

The Google Maps API is an example of an API service (“endpoint”) that requires an API key. If you give Google’s API a physical address (say “1001 Main Street, NY, NY”), the API will return the latitude and longitude of the most likely location (40.736124774992504, -73.82508447321075). However, without a valid API key, Google won’t answer your request. You need special permission. The API key lets Google know who you are and whether you have the right to access their map service. This is called authentication (as opposed to authorization, which we discuss later in the article.)

By the way, just to understand how the mechanism works, when we write, “We give Google’s API an address”, or “We send Google an API key”, we’re referring to sending information to a Google server (making a request through HTTP request methods like Post and Get) and receiving information back (getting a response from the same API). 

In sum:

If a developer wants to create a map application using Google’s near exhaustive list of world addresses, they will need to first sign up with Google and obtain an API key to have the right to use their Google Map API service.

Not all APIs require or use API keys

Some APIs don’t require an API key. For example, the Youtube URL that you use to watch a video is actually an API request that does not require an API key. It’s free to use from anywhere in the world, on any device, by all people (not just developers). That said, Youtube’s APIs also offers other services that require an API key, such as those that give (private or usually paid) information about channel playlists, comment history, usage statistics, and hundreds of other Youtube-owned data.  

Ease of use: API-first thinking

One central concern with any API is its ease of use. As we’ll repeat below in the context of security: ease of use is paramount to API usage. All API-first companies want to minimize all friction in using their API products. This includes making access to their APIs easy and secure, which is exactly what API keys are designed to provide. 

API keys – How they work 

As described above, an API key enables a server to identify any developer or application (the requestor or user) attempting to access its service(s). An API key also defines a set of access rights. Access rights authorize the requestor to take specific actions and forbid it from taking other actions. 

Let’s get into the details. 

Your API key is a unique identifier, usually a long string of characters

Your API keys are unique identifiers made up of a combination of numbers and letters. Some also contain non-alphanumerical characters. The unique identifier doesn’t signify anything on its own; it’s only meaning is its uniqueness. It’s akin to a password or secret code. 

API keys usually contain over 64 characters and are generated by system randomizers that create universal unique identifiers (often called GUIDs).

Getting access: authentication or failure

Think of an API key as a way of getting access to the data and functionality of an application via an API. Every API requestor sends the server a unique identifier, which the server uses to determine (authenticate) if the person or application requesting the service has a right to do so. 

If the server can’t authenticate the requester of an API call (request), it sends back a failure response. This is the basic idea behind why you create an API key: if you’re using a key that the server doesn’t recognize, then you won’t be able to use the service. 

However, if the server does recognize the API key and authenticates the holder of the key, then that user has the right to use the service. 

The next step is for the server to authorize the requestor to do one or more things. 

Authorization

The authorization process determines a requestor’s rights and scope. Authorization defines the exact manner in which an authenticated requestor can use an API. It involves defining your rights (what functionality and data you can access) and scope (how much data, how long you can use the API, and more).

Rights

The rights are about what you can do. If the requestor’s API key contains the right to search the data, then the requestor can read the data to perform the search. If the requestor has the right to write data, then the requestor can perform some or all write operations. Write access usually comes with more detail. For example, the requestor might have the right to update an index but not delete records. 

You can also combine rights. For example, a requestor might have both read and write capabilities, or just read-only. Typically, requestors have several APIs to perform different actions. For example:

  • Read-only for searches
  • Read & Write access for browsing as well as indexing (adds, updates, deletes) 
  • Admin access, which includes everything, including creating other APIs

Admin rights

Every API system has a global API key that not only allows read & write operations, but full access to anything else an API can do. For example, an Admin API allows applications and users to take meta actions like adding, removing, or modifying users, identifiers, rights, and scopes. 

Given the power of an Admin API key, you’ll want this API key to be completely secure – that is, hidden and locked-away from the public. The same applies to any write-level API key. Read-only keys may be more flexible depending on the use case. Reading business-sensitive data obviously needs higher security than searching products and film on a website.

Scope

Once a requestor has a right to do something, an API can restrict or expand the requestor’s capabilities within that right. For example, if a requestor has the general right to update indexes, the API key can limit the requestor access to only certain indexes. Or, the API key can scope read-only access that allows a requestor to access only a small number of records. 

You can use scope for further security by filtering out certain IP addresses. You can also set a time of validity, perhaps one request per day, or over a small daily number of requests over a period of 30 days.

Finally, an API key can provide filter-based limitations. For example, an API key can allow a user to update only “clothing” or “food” items. Or it can restrict a read-only requestor to perform pre-defined searches or filters.

A good example of the last point on restrictive API usage is where you grant read-only access, but restrict it with a filter that omits sensitive data. This adds additional security, allowing the requestor to see data designed only for public viewing. 

But security requires more discussion.     

Securing the API key

In terms of security, an API key only goes so far. Essentially, if a key is stolen or leaked, there’s no more security. 

A stolen or leaked API key

There are many ways someone can get an API key. Hackers can intercept the request, steal the key, and then change the request into something far more damaging. Or, as is more often the case, a developer may accidentally reveal the API key by sending it over the internet for anyone to easily find it. Or accidentally push it to a Git repo. Or write it on a napkin and leave it on the restaurant table.  

Security safeguards

Some security safeguards rely on additional security checks. Some of these methods require the requestor to do extra work, which undermines an API’s popularity. It’s worth keeping in mind API 101:

Ease of use is paramount to API usage, so you want to minimize all friction.

Here are some security safeguards that require no extra overhead or burden on the user of the API:

  • Creating rate limits, which controls the number of times the API can be called
  • Creating other limits or application restrictions to minimize attacks
  • Using attack-detection methods to signal unexpected behavior, referrers, or known attack behavior
  • Rejecting requests that are out of the norm or damaging to privacy or the data
  • And as mentioned above, removing access to non-sensitive data
  • Manually create or automate the generation of new API keys regularly

Technical note: Many of these safeguards can be added in the header as parameters in the API request.

Here are the most popular API security techniques that require developers to do more than just supply an API key:

  • Using a special kind of API key called a Secured API Key.
  • Logging in and using user ids and passwords.
  • Using authentication tokens (e.g., JWT tokens) for authentication and authorization.
  • Encrypting. For this to work, the user must have the same encryption software that the API server has. The encryption software converts the API key to unreadable data, which only the API server can understand.

The  Secured API Key: providing server-based security with a temporary API key

A Secured API Key contains additional security safeguards over the standard API key: (a) it’s ephemeral (created on-the-fly and temporary); as such, it cannot be seen on a dashboard to be modified or managed in any way. More importantly, (b) it contains the user’s id – thus, only one user can use the key.

Normally, API keys are generated once, for any user, and remain the same for life. However, there are two drawbacks with permanent keys:

  • Once someone steals the key, they will be able to use it until the theft is discovered and the key removed
  • If you need 10,000s of users to have unique keys, you’ll need to create and maintain all of them. And while you can automate the generation of new API keys, you’ll almost always need to manually changes the code.

Most production-level applications need something more secure and easier to manage – without any additional work.

How it works: A Secured API Key leverages the session and/or user id by including that information as part of the key generation. Essentially, the key is generated on-the-fly by combining the user identifier with the scope of the key (e.g., timeout limits, security filters). Once the key is generated, the requestor must always send the generated API key and its user id and scope. The API server will then re-generate the key using the user id and scope, then compare it to the key the user sent. If they differ, then it’s obviously a hack. 

This double-check logic is only one step towards better security. The next step is asking the API user to log in. 

Logging in – creating API keys with user IDs, passwords, JWT tokens, OAuth, and OpenID

The last security method we’ll mention here involves requiring the API user to log in. In this scenario, if the logon is successful, the API server issues a unique, unreadable token that the API user must use while they remain logged in. Additionally, the token includes the user credentials, making it difficult for anyone other than the user to send the token. 

Thus, we improve upon the temporary Secured API Key method in two important ways: 

  • JWT requires a logon.
  • JWT generates a token whose value contains an encrypted version of the user’s logon credentials. Those user credentials enable the API server to authenticate the user with every successive API request.

Learn more about the JWT token and how it differs from an API key.

Designing and implementing the best API – tracking usage

We’ve discussed the purposes of the API key, what it looks like, how it operates, and can and cannot be done with an API key. We’ve also gone into some detail about security. We’ll finish on another aspect: that of tracking API usage and improving the API. 

An API relies on user experience to improve its design and functionality. A company that wants to offer the absolute best API in the growing competitive API market, must know how its customers use their APIs. By logging every request – which requests, the number of requests, the success and failures of each request, the API provider adds reporting, debugging, and analysis to the API’s design and implementation.

About the author
Peter Villani

Sr. Tech & Business Writer

linkedinmediumtwitter

Recommended Articles

Powered byAlgolia Algolia Recommend

API keys vs JWT authorization - Which is best?
engineering

Julien Bourdeau

Software Engineer

What is an API?
product

Catherine Dee

Search and Discovery writer

How to build an API client for Javascript as a SaaS product
engineering

Peter Villani

Sr. Tech & Business Writer