ADR-006: Mercury API Authentication

Context

Plugins in Mercury will have API endpoints to realize the integrations into third-party systems.

Decision

Mercury's API will be authenticated using Bearer Tokens in the Authorization header.

A management API will be implemented in Solaris where users with the agents:manage permission will be able to create agent-bound API keys.

A new package is implemented in pkg/apikey to provide generic generation functions.

API Key Format

{prefix}.{version}_{id}_{key}

• Prefix: Prefix to identify key type (e.g. sca for STREAM Connect Agent)
• Version: Key version, to allow for future changes without breaking existing keys
• ID: A short (16 bytes) cryptographically secure random ID of the key, to simplify key lookup in case multiple keys are used
• Key: A 32 byte cryptographically secure random key

The API key will be presented to the user after generation. The key is stored hashed using the Argon2id hashing function. The API Key is only sent to Mercury in hashed form, the actual key will only be known to the user.

If no API key is configured, Mercury must reject all requests (except those to health endpoints like /livenesszs or /readinessz). There must never be a configuration where Mercury's API is unprotected. Upon receiving a request, Mercury must verify the key format and compare the key portion with the hashed key, using the same Argon2id paramaters as Solaris used when hashing. Only if the key is valid, the request is permitted.

Revoking an API key must also revoke the API key from Mercury itself in a timely manner.