API authentication best practices

Verify the identify of a user or application.

Problem statement

Virtually all commercial APIs require consumers to authenticate themselves, in order to prevent unauthorized access, data breaches, and abuse. Freely available APIs that manage unsensitive data are also vulnerable to attacks that can compromise their availabilty, such as a denial of service attack. A authentication mechanism makes it easier to implement security measures such as rate limiting on a per-client basis.

It is also desirable for API products to track usage on a per user or per application basis, in order to discover and prioritize enhancements.

Success criteria

Security organizations are often viewed as cost centers, which can make tracking meaningful metrics for security features, like authentication, difficult. In the event of a breach, the quality of an authentication system can impact other incident response metrics.

Counter metrics ensure that the design and implementation of the authentication does not adversely impact other goals of the API, such as improving its developer experience.

Product requirements

All requests to the API should be authenticated, even where the requested data is non-sensitive, public information.

APIs should also distinguish whether clients must be confidential applications such as servers owned and operated by the customer, or unconfidential applications such as web or mobile applications.

User stories

As an API consumer, I want my data to be invisible to outside parties, so that my business's property is protected.Functional

As a developer, I want the API's authentication mechanism to be simple, so that I can focus on my integration's business logic.Developer Experience

Authentication can often be a stumbling block for new developers getting starting with an API. Depending on your API product, this may result in fewer developers converting into activated customers.

Your documentation's Getting Started guide should describe how to authenticate in clear, unambigous steps that anyone can follow.

It is good practice include a way for the developer to confirm that they have successfully authenticated, and track this step as part of the developer onboarding funnel.

As an client-side web or native application developer, I want the API's authentication mechanism to not require customers to hold credentials securly, so that I can don't need to build a backend server to use the API.Security

Web or mobile applications should always be treated as untrusted, since their source code and network traffic can be access more easily by malicous actors.

Do not require customers to embed permanent credentials such as API keys or client secrets within such applications.

As an API owner, I want to deactivate and reissue identities to customers, so that I can prevent further data loss in the event of a leak.OperationsSecurity

Security breaches may happen on either the provider's side and consumer's side. In the event of credentials leaking, the authentication mechanism should provide a means of immediately revoking any compromised credentials and reissue new ones to customers.

This implies that the authentication mechanism should require a non-confidential user or application identifier in addition to a confidential token, key or password, in order to enable business continuity in the event of a breach.

As an API owner, I want to monitor and log authentication-related activities, so that I can identify suspicious activities and troubleshoot incidents.Security

At a minimum, API access logs should record the "when, where, who and what" of each event. Take care not to output any sensitive information, such as API keys or PII.

When logging the user or application's identity, make sure that your authentication mechanism does not regard identity as sensitive information.

See Logging Cheat Sheet.

As an API owner, I want the authentication mechanism to be efficient and scalable, so that the API's archicture does not have to make unreasonable trade-offs between security and performance.Performance

Security best practices for microservice architectures recommends that internal services authenticate with each other during service-to-service communication. This authentication mechanism should be designed so as not to impose a large overhead on the overall API request latency.

See Microservices Security Cheat Sheet for more recommendations.

Explore design patterns

API examples

Here are some examples of public APIs and their authentication mechanisms:

Related topics