Skip to content

API Key Authentication

This document describes how API key authentication is handled in the Registration Backend service.

Overview

All API endpoints require authentication via API keys. Requests must include a valid API key in the x-api-key HTTP header.

How It Works

Request Flow

  1. Every incoming request passes through the authMiddleware defined in app/root.tsx
  2. The middleware extracts the x-api-key header from the request
  3. The key is validated against the list of valid API keys
  4. If valid, the request proceeds; otherwise, an error response is returned

API Key Storage

API keys are stored in AWS Secrets Manager under the secret name registration-backend-api-keys. The secret contains a JSON array of valid API keys:

["key-1", "key-2", "key-3"]

Key Loading & Caching

The middleware uses a two-tier approach for loading API keys:

  1. Environment Variable Cache: First checks APP_API_KEYS environment variable
  2. Secrets Manager Fallback: If not in env, fetches from AWS Secrets Manager using the ARN stored in APP_API_KEYS_SECRET_ARN
  3. Caching: After fetching from Secrets Manager, keys are cached in APP_API_KEYS to avoid repeated API calls

This caching happens per Lambda instance, so keys are loaded once per cold start.

Configuration

Environment Variables

Variable Description
APP_API_KEYS JSON array of valid API keys (cached)
APP_API_KEYS_SECRET_ARN ARN of the Secrets Manager secret
SKIP_MIDDLEWARE_AUTH Set to "true" to bypass auth (dev only)

Infrastructure (CDK)

The secret is created in cdk.mts and the Lambda function is granted read access:

const apiKeysSecret = new secretsmanager.Secret(
  stack,
  "RegistrationBackendApiKeys",
  {
    secretName: "registration-backend-api-keys",
    description: "API keys for the Registration Backend application",
  },
);

// Lambda is granted read access
apiKeysSecret.grantRead(remix.implementation.lambda);

Managing API Keys

Adding/Removing Keys

To manage API keys via the AWS Console:

  1. Open the AWS Secrets Manager Console for the environment you want to change the keys (Stage or Prod).
  2. Select the appropriate region for your environment (eu-central-1)
  3. Search for registration-backend-api-keys and click on the secret
  4. Click Retrieve secret value to view the current keys
  5. Click Edit to modify the secret
  6. Click Plaintext

  7. Update or add an array with API keys you created:

    ["existing-key", "new-key-to-add"]

  8. Click Save

Note: API keys are stored in the shared Bitwarden bucket PIT/Developers/Acquisition and Registration. Remember to update this location when keys are added, deleted or changed.

Note: Each consumer should have a unique API key. Do not share keys across multiple consumers or environments.

Note: Changes to the secret take effect on the next Lambda cold start. To apply changes immediately, redeploy the Lambda function.

Local Development

For local development, you can:

  1. Set SKIP_MIDDLEWARE_AUTH=true to bypass authentication entirely
Last updated: March 31, 2026 at 13:40
By: renovate-token-app[bot]