Authentication

Authentication is essential for most public APIs and is often the most common point of friction when it comes to onboarding with an API. This API Commons property is often a human-readable affair, and will need to become something that is machine-readable if we are going to scale things.

Also known as: Auth, AuthN, Identity

Example

- type: Authentication
  url: https://developers.example.com/authentication

Standards

IETF RFC 7235 — HTTP/1.1 Authentication
IETF RFC 9110 — HTTP Semantics
IETF RFC 6749 — OAuth 2.0 Authorization Framework
IETF OAuth 2.1 (draft)
IETF RFC 9700 — Best Current Practice for OAuth 2.0 Security
IETF RFC 8252 — OAuth 2.0 for Native Apps
IETF RFC 8628 — OAuth 2.0 Device Authorization Grant
IETF RFC 8414 — OAuth 2.0 Authorization Server Metadata
IETF RFC 7519 — JSON Web Token (JWT)
IETF RFC 7517 — JSON Web Key (JWK)
IETF RFC 7591 — OAuth 2.0 Dynamic Client Registration
IETF RFC 8705 — Mutual TLS Client Authentication for OAuth 2.0
OpenID Foundation OpenID Connect Core 1.0
OpenID Foundation OpenID Connect Discovery 1.0
W3C WebAuthn Level 3
FIDO Alliance FIDO2
OASIS SAML 2.0
IETF SCIM 2.0 — System for Cross-domain Identity Management

HTTP Headers

Header	Direction	Spec	Description
`WWW-Authenticate`	response	RFC 9110 §11.6.1	Server challenges the client to authenticate.
`Authorization`	request	RFC 9110 §11.6.2	Carries client credentials (Basic, Bearer, etc.).
`Proxy-Authenticate`	response	RFC 9110 §11.7.1	Proxy challenges the client to authenticate.
`Proxy-Authorization`	request	RFC 9110 §11.7.2	Carries credentials for an HTTP proxy.

Status Codes

401 Unauthorized — RFC 9110 §15.5.2 — Authentication required or failed.
403 Forbidden — RFC 9110 §15.5.4 — Authenticated identity lacks permission.
407 Proxy Authentication Required — RFC 9110 §15.5.8

Well-Known Paths

/.well-known/openid-configuration — OpenID Connect Discovery 1.0 — OIDC issuer metadata.
/.well-known/oauth-authorization-server — RFC 8414 — OAuth 2.0 authorization-server metadata.
/.well-known/oauth-protected-resource — RFC 9728 — OAuth 2.0 protected-resource metadata.
/.well-known/jwks.json — RFC 7517 (de facto path) — JSON Web Key Set published by the issuer.

Media Types

application/jwt — RFC 7519
application/jose — RFC 7515
application/x-www-form-urlencoded — OAuth 2.0 token endpoint request bodies (RFC 6749 §4.1.3).
application/json — Token endpoint responses, JWKS payloads.

OpenAPI Expression

components.securitySchemes (OpenAPI 3.x)
Types: apiKey, http (basic, bearer, digest), oauth2, openIdConnect, mutualTLS
security (OpenAPI 3.x) — Operation-level or global requirement referencing a defined securityScheme.

Link Relations

authorization_endpoint — OIDC Discovery (in JSON, not Link header)
token_endpoint — OIDC Discovery
jwks_uri — OIDC Discovery

Governance Rules

oas-security-defined (Spectral built-in) — Operations must reference a defined security scheme.
oas3-server-not-example.com (Spectral built-in) — Server URL must not be a placeholder (auth often tied to base URL).
oas-tag-description (Spectral built-in) — Tags need descriptions — auth tags benefit from explicit scope notes.

Risk & Compliance

OWASP:

OWASP API Security Top 10: API2:2023 Broken Authentication
OWASP API Security Top 10: API5:2023 Broken Function Level Authorization

Compliance:

GDPR — lawful basis for processing requires authenticated identity for data-subject rights
HIPAA 45 CFR §164.312(a) — access controls and unique user identification
PCI DSS v4 Req. 8 — identify and authenticate access to system components
SOC 2 CC6.1 — logical and physical access controls
NIST SP 800-63B — digital identity guidelines

Security: Weak or missing authentication enables enumeration, account takeover, and data exfiltration. Default to short-lived bearer tokens, refresh-token rotation with reuse detection, mTLS for service-to-service, and WebAuthn/FIDO2 for human factors.

Tools

Auth0 — Managed IdP
Okta — Managed IdP
Keycloak — Self-hosted IdP (Apache-2.0)
Ory Hydra / Kratos — OAuth/OIDC server (Apache-2.0)
oauth.tools — Debugger
jwt.io — Debugger

Suggested Metrics

auth_success_rate — Successful authentications divided by total attempts; baseline for brute-force / credential-stuffing detection.
token_issuance_p95_ms — 95th-percentile latency of the token endpoint.
401_rate — Share of responses that are 401 Unauthorized; spikes indicate token churn or breakage.
refresh_token_reuse_detected — Count of detected refresh-token reuse events (RFC 6749 §10.4 / OAuth 2.1 §6.1).
mfa_enrolment_rate — Fraction of accounts enrolled in a phishing-resistant second factor.

Example Implementations

Stripe — API keys (publishable / secret / restricted), connected-account headers.
GitHub — PATs, fine-grained tokens, OAuth apps, GitHub Apps with JWT-signed assertions.
Google — OAuth 2.0, Application Default Credentials, service-account JWTs.
Microsoft Graph — Microsoft Entra ID (OIDC) with delegated and application permissions.