Pattern Sections
Pattern: API Key 
a.k.a. Access Token, Provider-Allocated Client Identifier
Context
An API provider offers services to subscribed participants only. For various reasons, such as establishing a Rate Limit or Pricing Plan, one or more clients have signed up and want to use the services. These clients have to be identified.
Problem
How can an API provider identify and authenticate clients and their requests?
Forces
When identifying and authenticating clients on the API provider side, the following forces come into play:
- Establishing basic security
- Access control
- Avoiding the need to store or transmit user account credentials
- Decoupling clients from their organization
- Security versus ease of use
- Performance
Pattern forces are explained in depth in the book.
Solution
As an API provider, assign each client a unique token —- the API Key -— that the client can present to the API endpoint for identification purposes.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
In the following call to the Cloud
Convert API a new process to convert a DOCX file to PDF format is
started. The client creates a new conversion process by informing the
provider of the desired in- and output format, passed as two
Atomic
Parameters in the body of the request (the input file has to be
provided by a second call to the API). For billing purposes, the client
identifies itself by passing the API
Key gqmbwwB74tToo4YOPEsev5 in the
Authorization header of the request, according to the
HTTP/1.1 Authentication RFC 7235
specification. HTTP supports various types of authentication, here the
RFC 6750
Bearer type is used:
POST https://api.cloudconvert.com/process
Authorization: Bearer gqmbwwB74tToo4YOPEsev5
Content-Type: application/json
{
"inputformat": "docx",
"outputformat": "pdf"
}The API provider can thus identify the client and charge their account.
Are you missing implementation hints? Our papers publications provide them (for selected patterns).
Consequences
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
Many public Web APIs use the API Key concept, sometimes under different names (such as access token). A few examples are:
- The YouTube Data API supports both OAuth 2.0 as well as API Keys. Clients have to generate different API Keys, depending on where these keys are used, e.g., server keys, browser keys, iOS and Android keys. These keys can then only be used by the configured apps (in case of the iOS and Android apps), IP addresses or domain names. This additional layer of protection makes a specific key unusable outside of the specified app. This is done to avoid that an attacker could, for example, simply extract the key from an installed Android application and use it to make requests on behalf of that application.
- The GitHub API’s primary means of authentication and authorization
is OAuth, but basic
authentication with a username and token – the
API Key – is also supported. Here,
the API Key is not sent via HTTP
header but through the password parameter of the basic authentication.
For example, a request to access the user resource using the cURL
command line tool looks as follows:
curl -u username:token https://api.github.com/user. - The API of online payment provider Stripe uses a
publishable key and a secret key. The secret key takes
the role of an API Key and is
transmitted in the
Authorizationheader of each request, whereas the publishable key is just the account identifier. This naming scheme might be surprising for clients expecting the secret key to be kept private, like Amazon’s secret key, which is never transmitted and only used to sign requests.
More Information
Related Patterns
Many web servers use Session Identifiers as described by Fowler (2002) to maintain and track user sessions across multiple requests; this is a similar concept. In contrast to API Keys, Session Identifiers are only used for single sessions and then discarded.
The Security Patterns in Schumacher et al. (2006) provide solutions satisfying security requirements such as Confidentiality, Integrity, and Authentication/Authorization, and discusses their strengths and weaknesses in detail. Access control mechanisms, such as Role-based Access Control (RBAC) or Attribute-based Access Control (ABAC), can complement API Keys and other approaches to authentication; these access control practices require one of the described authentication mechanisms to be in place.
Other Sources
Chapter 12 of the RESTful Web Services Cookbook Allamaraju (2010) is dedicated to security and presents six related recipes. Pautasso, Ivanchikj, and Schreier (2016) covers two related patterns of alternative authentication mechanism in a RESTful context, Basic Resource Authentication and Form-Based Resource Authentication.
Siriwardena (2014) provides a comprehensive discussion on securing APIs with OAuth 2.0, OpenID Connect, JWS, and JWE. Chapter 9 of Sturgeon (2016) has a discussion of conceptual and technology alternatives and instructions on how to implement an OAuth 2.0 server. The OpenID Connect specification deals with user identification on top of the OAuth 2.0 protocol.