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 a 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 are the most-often used method of securing an API. API keys vs JWT auth , The 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). Google Maps API 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, , or we’re referring to sending information to a Google server (making a request like Post and Get) and receiving information back (getting a response from the same API). “We give Google’s API an address” “We send Google an API key”, through HTTP request methods 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 that you use to watch a video is actually an API request that does not require an API key. Youtube URL It’s free to use from anywhere in the world, on any device, by all people (not just developers). That said, 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. Youtube’s APIs 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. This includes making access to their APIs easy and secure, which is exactly what API keys are designed to provide. All API-first companies want to minimize all friction in using their API products. API Keys – How They Work As described above, an API key enables a server to identify any developer or application (the or ) attempting to access its service(s). requestor user An API key also defines a set of . Access rights authorize the requestor to take specific actions and forbid it from taking other actions. access rights Let’s get into the details. Your API Key is a Unique Identifier, Usually a Long String of Characters Your API keys are made up of a combination of numbers and letters. Some also contain non-alphanumerical characters. unique identifiers 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 (often called s). universal unique identifiers GUID 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 ( ) if the person or application requesting the service has a right to do so. authenticate 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 recognize the API key and authenticates the holder of the key, then that user has the right to use the service. does The next step is for the server to the requestor to do one or more things. authorize Authorization The authorization process determines a requestor’s and . Authorization defines the exact manner in which an authenticated requestor can use an API. rights scope It involves defining your (what functionality and data you can access) and (how much data, how long you can use the API, and more). rights scope 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 the data to perform the search. read If the requestor has the right to data, then the requestor can perform some or all operations. Write access usually comes with more detail. For example, the requestor might have the right to an index but not records. write write update delete You can also combine rights. For example, a requestor might have read and write capabilities, or just read-only. Typically, requestors have several APIs to perform different actions. For example: both Read-only for searches. Read & Write access for browsing as well as indexing (adds, updates, deletes). , which includes everything, including creating other APIs. Admin access 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 or burden on the user of the API: no extra overhead 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. Many of these safeguards can be added in the header as parameters in the API request. Technical note: 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 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. Secured API Key More importantly, (b) it contains the user’s id – thus, only one user can use the key. Normally, API keys are generated , for user, and remain the same for life. However, there are two drawbacks with permanent keys: once any 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 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. and 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 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. 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 successive API request. every Learn more about the and how it differs from an API key. JWT token 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.
