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.

Helm Chart Configuration​

For containerized deployments using Kubernetes and Helm, API keys are configured via environment variables.

Helm Values Configuration​

File: values.yaml (Helm chart: ewa-integration)

# Example environment variable configuration
env:
  - name: Authentication__UseApiKey
    value: "true"
  - name: Authentication__ApiKeys__0
    valueFrom:
      secretKeyRef:
        name: eoc-integration-secrets
        key: apikey-eoc-1
  - name: Authentication__ApiKeys__1
    valueFrom:
      secretKeyRef:
        name: eoc-integration-secrets
        key: apikey-eoc-2
  - name: Authentication__ApiKeys__2
    valueFrom:
      secretKeyRef:
        name: eoc-integration-secrets
        key: apikey-eoc-3

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 new secret value
kubectl create secret generic eoc-integration-secrets-new \
  --from-literal=apikey-client-old="3B3D3A3F-0F9E-4E8B-AC76-66C20B2F2F8E" \
  --from-literal=apikey-client-new="9F8E7D6C-5B4A-3928-1716-0F9E8D7C6B5A" \
  --namespace=<namespace>

# Update Helm values to reference both keys
# values.yaml:
env:
  - name: Authentication__ApiKeys__0
    valueFrom:
      secretKeyRef:
        name: eoc-integration-secrets-new
        key: apikey-client-old
  - name: Authentication__ApiKeys__1
    valueFrom:
      secretKeyRef:
        name: eoc-integration-secrets-new
        key: apikey-client-new

# Deploy updated configuration
helm upgrade ewa-integration ./Helm/ewa-integration -n <namespace>

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