Skip to main content

API Key Authentication

Table of Contents​

Overview​

The EOC (Emergency Operations Centers) Integration Service provides API key authentication to secure access to emergency mission data endpoints.

This authentication mechanism ensures that only authorized external systems can submit mission data, resource status updates, and patient information to the EWA platform.

Key Features:

  • Header-based API key authentication using the x-api-key header
  • Support for multiple API keys (one per client system)
  • Configurable authentication (can be disabled for development/testing)
  • Standard ASP.NET Core authentication pipeline integration
  • Validation at application startup to prevent misconfiguration

Generating API Keys​

API keys should be strong, unique, and unpredictable values.

The API key can be a GUID/UUID or Cryptographically Secure Random String.

Examples:

PowerShell:

[Guid]::NewGuid().ToString()
# Output: 3B3D3A3F-0F9E-4E8B-AC76-66C20B2F2F8E

PowerShell:

$bytes = New-Object byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
[Convert]::ToBase64String($bytes)
# Output: kX8bN9pQ2mL5vW3cZ7fR4tY6uH1jK0aS9dG8eP3xQ2w=

Server Configuration - EOC Integration Service Configuration​

Application Settings​

API key authentication is configured in the appsettings.json file using the Authentication section.

Production Configuration Example:

{
  "Authentication": {
    "UseApiKey": true,
    "ApiKeys": [
      "3B3D3A3F-0F9E-4E8B-AC76-66C20B2F2F8E", // Can be a GUID
      "7A9E2F1B-4D8C-4E6A-B5F3-9C8D7E6F5A4B",
      "kX8bN9pQ2mL5vW3cZ7fR4tY6uH1jK0aS9dG8eP3xQ2w" // Or a Cryptographically Secure Random String
    ]
  },
}
note

The "UseApiKey": false setting is only for development and testing, never use it in production.

Kubernetes Configuration​

On Kubernetes, EWA is deployed by Octopus Deploy from Products/EWA/.deploy, and the settings above are passed as environment variables. Authentication__UseApiKey is set in .deploy/kubernetes/services/definitions.ts, and Authentication__ApiKeys__0 is mapped from a secret in .deploy/kubernetes/secrets/registry.ts. Each extra key needs its own Authentication__ApiKeys__<n> mapping there.

Client Configuration - EOC System Configuration​

HTTP Header Format​

All requests to EWA EOC Integration API must include the x-api-key header with a valid API key value when authentication is enabled on the server.

The API key in the request header is only valid if it matches the API keys configured in the EOC Integration Service settings on the server side.

Header Specification:

x-api-key: <your-api-key-value>

cURL Examples​

curl -X POST 'https://<your-server>/integration/api/import' \
  -H 'x-api-key: 3B3D3A3F-0F9E-4E8B-AC76-66C20B2F2F8E' \
  -H 'Content-Type: application/json' \
  -d '{
        "central_mission_id": 22224,
        "emcc_id": "InsightSimulator",
        "dispatch_code": "H.20.02",
        "dispatch_description": "Hodepine - Slag mot hodet og bruker blodfortynnende medisiner",
        "dt_central_alerted": "2026-01-21T05:05:00+01:00",
        "emergency_code": "Urgent",
        "problem_description": "Mulig overdose.",
        "ambulances": [
            {
            "resource_id": 1,
            "resource_radio_id": "TestResource",
            "dt_ambulance_alerted": "2026-01-21T05:06:00+01:00",
            "pos_ambulance_alerted": {
                "lat": 58.346801,
                "long": 8.596954
            }
            }
        ],
        "patients": [],
        "callers": []
    }'

Operational Notes​

API Key Rotation Strategy​

Regular key rotation enhances security. Use this zero-downtime approach:

Step 1: Generate New API Key​

$newApiKey = [Guid]::NewGuid().ToString()
Write-Host "New API Key: $newApiKey"

Step 2: Add New Key to Server Configuration​

Add the new key to the ApiKeys array without removing the old key:

{
  "Authentication": {
    "UseApiKey": true,
    "ApiKeys": [
      "3B3D3A3F-0F9E-4E8B-AC76-66C20B2F2F8E",  // Old key (to be rotated)
      "9F8E7D6C-5B4A-3928-1716-0F9E8D7C6B5A"   // New key
    ]
  }
}

For Kubernetes deployments: add the new key as an extra Authentication__ApiKeys__<n> mapping in .deploy (see Kubernetes Configuration) and deploy the release through Octopus.

Step 3: Update Client System​

Provide the new API key to the client system administrator and have them update their configuration:

// Old configuration
client.DefaultRequestHeaders.Add("x-api-key", "3B3D3A3F-0F9E-4E8B-AC76-66C20B2F2F8E");

// Updated configuration
client.DefaultRequestHeaders.Add("x-api-key", "9F8E7D6C-5B4A-3928-1716-0F9E8D7C6B5A");

Step 4: Verify Client System​

Confirm the client system is successfully using the new API key by monitoring logs and verifying successful requests.

Step 5: Remove Old Key​

After confirming all client systems are using the new key (recommended wait: 7-30 days), remove the old key:

{
  "Authentication": {
    "UseApiKey": true,
    "ApiKeys": [
      "9F8E7D6C-5B4A-3928-1716-0F9E8D7C6B5A"   // New key only
    ]
  }
}

Secure Transmission​

  1. HTTPS is Mandatory

    • Never transmit API keys over unencrypted HTTP
    • Ensure TLS 1.2 or higher is enforced on the server
    • Use valid, trusted SSL/TLS certificates (not self-signed in production)

  2. Storage and Secret Management

    • Store API keys in secure configuration (not in source code)
    • Use environment variables or secure credential stores
    • Never commit API keys to version control systems
    • Rotate keys immediately if accidentally exposed