[ADP-55] API Key

Overview

API Key is a method for API authentication, commonly used to identify and authorize users. This serves as a complement to ADP-47. Typically, API Key is not based on JWT or OAuth.

Differences about key and token

API Keys and tokens have several key differences:

Structure:
- API Keys are usually simple strings
- Tokens (like JWT) contain encoded information and claims
Purpose:
- API Keys primarily focus on identification and authentication
- Tokens often include authorization information and user context
Lifespan:
- API Keys typically have longer lifespans and may not expire
- Tokens usually have shorter lifespans and require refresh
Security:
- API Keys are more vulnerable if compromised since they have longer lifespans
- Tokens provide better security through short expiration and refresh mechanisms
Use Cases:
- API Keys: Simple authentication, server-to-server communication
- Tokens: User sessions, OAuth flows, stateless authentication

Guidance

API Key MAY be rotatable.
API Key SHOULD be revokable.
SHOULD implement an expiration mechanism for API Keys.
- SHOULD provide no expiration carefully with revoke functionality.
SHOULD NOT hardcode API Key.
MAY consider providing different permissions for different API Keys.
MAY differentiate user-level API keys and system-level (machine to machine) API Keys.
API Keys SHOULD be stored securely, such as in environment variables or secure vaults.
API Keys MUST be transmitted over HTTPS to prevent man-in-the-middle attacks and interception.
API Keys SHOULD only be displayed once at the time of generation. When listing API Keys through an API or user interface, the actual key value SHOULD NOT be returned from the server. The complete API Key value SHOULD only be provided in the response of the initial key creation request, unless specific security requirements dictate otherwise.

Implementation

Producing

Most API keys are only visible to the user at the time of generation; in some cases, the application allows the user to view the key again later.

Consuming

The recommended methods for passing API keys are listed below in order of preference:

(RECOMMENDED) Authorization: Bearer is the most commonly used method.
Authorization: ${custom schema}. See ADP-363.
API-Key (exactly, not a common HTTP header).
(NOT RECOMMENDED) X-API-Key (retired by RFC6648 for x- prefix headers).

TIP

While API-Key is not a standard header, some applications supported it before the standardization of the Authorization header. Therefore, the recommended approach for API key usage is to use the standard Authorization: Bearer header. If you need to distinguish between different types of keys, you MAY add prefixes. For example, OpenAPI uses sk-proj- prefix for personal API keys and sk-svcacct- prefix for service account API keys. Keys without any notable prefix can be interpreted as JWT tokens.

The other services which put API Key in the Authorization: Bearer header:

References

Example Request

http

POST HTTP/1.1 https://api.apidog.com/v1/projects/552408/export-openapi?locale=en-US

X-Apidog-Api-Version	2024-03-28
Authorization	Bearer APS-XXXXX
User-Agent	Apidog/1.0.0 (https://apidog.com)
Content-Type	application/json
a	
Accept	*/*
Cache-Control	no-cache
Host	api.apidog.com
Accept-Encoding	gzip, deflate, br
Connection	keep-alive
Body:
Body Type : application/json
{
  "scope": {
    "type": "ALL",
    "excludedByTags": ["pet"]
  },
  "options": {
    "includeApidogExtensionProperties": false,
    "addFoldersToTags": false
  },
  "oasVersion": "3.1",
  "exportFormat": "JSON"
}

[ADP-55] API Key ​

Overview ​

Guidance ​

Implementation ​

Producing ​

Consuming ​

References ​

Example Request ​