BitzOrcas uses a three-scheme authentication model with automatic forwarding based on request headers. The PolicyScheme (MultiScheme) selects the correct handler based on which header is present.

Scheme forwarding

Request arrives
       │
       ├── Has X-Signature header? → HMAC scheme
       ├── Has X-API-Key header?   → API Key scheme
       └── Otherwise               → JWT Bearer scheme

JWT Bearer (User callers)

For interactive user authentication:

Parameter	Source	Validation
`Jwt:Secret`	Configuration	Required, ≥ 32 characters
`Jwt:Issuer`	Configuration	Required, validated
`Jwt:Audience`	Configuration	Required, validated
`ClockSkew`	Hardcoded	`TimeSpan.Zero` (no tolerance)

{
  "Jwt": {
    "Secret": "your-secret-at-least-32-characters-long",
    "Issuer": "bitzorcas-api",
    "Audience": "bitzorcas-client"
  }
}

JWT claims

Claim	Description
`sub` / `user_id`	User identifier
`tenant_id`	Tenant identifier
`roles`	Assigned roles
`exp`	Expiration (UTC)
`iat`	Issued at (UTC)

HMAC (Application callers)

For server-to-server authentication:

Component	Description
Header	`X-Signature`
Algorithm	HMAC-SHA256
Credentials	`Hmac:Clients` configuration
Nonce	Anti-replay via `INonceStore`
Fail-closed	Unregistered clients → 401

{
  "Hmac": {
    "Clients": {
      "service-a": "shared-secret-here",
      "service-b": "another-secret"
    }
  }
}

HMAC request signing

Client constructs canonical request string
Computes HMAC-SHA256 with shared secret
Sends X-Signature: {timestamp}.{signature}
Server validates signature and nonce (anti-replay)

API Key (Application callers)

Simple key-based authentication for service integration:

Component	Description
Header	`X-API-Key`
Storage	SHA-256 hash only (plaintext never stored)
Credential format	`prefix_description` → `prefix_identifier`

{
  "ApiKeys": {
    "boa_integration-key": {
      "KeyPrefix": "boa",
      "TenantId": "100",
      "Scopes": ["tickets.read", "tickets.write"]
    }
  }
}

Development test fixtures

Only in Development mode, test credentials are injected:

HMAC: test-client with secret test-secret
API Key: boa_test_integration-key with sandbox scopes

Authentication