barrel_mcp_auth_apikey (barrel_mcp v2.0.2)

View Source

API key authentication provider for barrel_mcp.

Supports API key authentication via X-API-Key header, custom headers, or Authorization header with ApiKey scheme.

Configuration Options

  • keys - Map of API key to auth info, or list of valid keys
  • verifier - Custom verification function
  • header_name - Custom header name (default: X-API-Key)
  • hash_keys - If true, stored keys are SHA256 hashes

See also: barrel_mcp_auth.

Summary

Functions

authenticate(Request, State)

Authenticate a request using API key.

challenge(Reason, State)

Generate authentication challenge.

hash_key(Key)

Hash an API key using the legacy SHA-256 hex format. Kept for migration; use hash_key/2 with a pepper for new deployments.

hash_key(Key, Opts)

Hash an API key with the chosen format.

init(Opts)

Initialize the API key provider.

verify_key(Key, Stored)

Constant-time comparison of a presented Key against a Stored digest. Accepts only the legacy hex SHA-256 format — the modern hmac-sha256$... format requires the server-side pepper, which verify_key/3 takes explicitly. This shim rejects HMAC-format inputs so callers don't accidentally treat them as verified.

verify_key(Key, Stored, Pepper)

Constant-time comparison of a presented Key against a Stored digest, with the server-side Pepper used for the hmac-sha256$... format. The Pepper is ignored for legacy hex SHA-256 digests (they were produced without a pepper). Use this from any code that owns the pepper (config tooling, tests) — the auth provider's internal authenticate path goes through verify_against_state/2 which already has the pepper in state.

Functions

authenticate(Request, State)

-spec authenticate(map(), map()) ->
                      {ok, barrel_mcp_auth:auth_info()} | {error, barrel_mcp_auth:auth_error()}.

Authenticate a request using API key.

challenge(Reason, State)

-spec challenge(barrel_mcp_auth:auth_error(), map()) -> {integer(), map(), binary()}.

Generate authentication challenge.

hash_key(Key)

-spec hash_key(Key :: binary()) -> binary().

Hash an API key using the legacy SHA-256 hex format. Kept for migration; use hash_key/2 with a pepper for new deployments.

hash_key(Key, Opts)

-spec hash_key(Key :: binary(), Opts :: map()) -> binary().

Hash an API key with the chosen format.

Opts may include:

  • pepper (binary, required for the new format) — server-side secret mixed into the HMAC. Stored format becomes hmac-sha256$<base64(hash)>.

init(Opts)

-spec init(map()) -> {ok, map()}.

Initialize the API key provider.

verify_key(Key, Stored)

-spec verify_key(Key :: binary(), Stored :: binary()) ->
                    ok | {error, invalid_credentials} | {error, pepper_required}.

Constant-time comparison of a presented Key against a Stored digest. Accepts only the legacy hex SHA-256 format — the modern hmac-sha256$... format requires the server-side pepper, which verify_key/3 takes explicitly. This shim rejects HMAC-format inputs so callers don't accidentally treat them as verified.

verify_key(Key, Stored, Pepper)

-spec verify_key(Key :: binary(), Stored :: binary(), Pepper :: binary() | undefined) ->
                    ok | {error, invalid_credentials}.

Constant-time comparison of a presented Key against a Stored digest, with the server-side Pepper used for the hmac-sha256$... format. The Pepper is ignored for legacy hex SHA-256 digests (they were produced without a pepper). Use this from any code that owns the pepper (config tooling, tests) — the auth provider's internal authenticate path goes through verify_against_state/2 which already has the pepper in state.