4.1 Tenant API Keys (X-API-Key)

Tenant API Keys are issued by tenant owners or admins to allow external systems to read data from Gamers Lab. They are passed in the X-API-Key request header.

What they can do:

• Read match history
• Read leaderboards
• Read event records
• Read tenant logs
• Subscribe to streaming endpoints (if enabled)
• Access is controlled via allow/deny flags, live scope, and data profiles (field exclusion, PII masking)
• A four-stage middleware pipeline enforces: use-case → read-only → rate limit → post-response usage tracking

They cannot write game data. The only non-read methods allowed for tenant API keys are the explicit allowAuth authentication endpoints.

Security characteristics:

• Stored as key_hash (never plaintext)
• Flagged (allow_data_api, allow_live_events, allow_active_match_data, live_events_scope)
• Access shaped by profiles (LiveEventsProfileId, HistoricalDataProfileId) that control field visibility and PII masking
• Rate limited (Redis Lua-based atomic minute/hour counters)
• Can be revoked
• Can expire

Subscriber keys (subtype of Tenant API Keys): Subscriber keys are still tenant API keys, but they are issued to end users (subscribers) and tracked separately for billing and access control.

• Stored in bus_tenant_api_keys with created_by_type = 'subscriber' and created_by_user_id
• Subscription state lives in bus_tenant_subscriptions
• Same read-only guarantees, auth POST allowlist, and flags as other tenant API keys

Key count limits:

• Default max read keys (API keys): 3 per tenant.
• Per-tenant overrides are supported. Platform admins can bypass count limits.

Read key rate limits (per key):

• Default: 60 requests/minute, 1,000 requests/hour.
• Derived from tenant/company plan. Subscriber keys use subscriber plan limits when set.
• Per-key limits are capped by the plan ceiling.

Rate limit behavior:

• Exceeding limits returns HTTP 429 with Retry-After and X-RateLimit-Reset headers.
• Read rate limiting is fail-open by default, except for live/streaming paths which are fail-closed.

Key management:

• Keys can be rotated, revoked, or deleted.
• Rate limits are adjusted via plan changes, not per-key edits.
• Key names: 1–100 characters. Descriptions: up to 500 characters.

4.1.1 Key Lifecycle

A tenant API key is a read-only credential used by dashboards, analytics tools, and subscriber integrations to query game data. Unlike player JWTs or game auth keys, it carries no session and does not expire by inactivity — it is active until explicitly rotated, revoked, or deleted.

The secret value is shown once at creation or rotation. The platform stores only a SHA-256 hash of the key and never exposes the plaintext again after that single response.

Key format: Keys use the prefix sk_live_ followed by cryptographically random bytes. A short prefix (the first visible characters) is stored alongside the hash so keys can be identified in the UI without revealing the secret.

Key fields:

Use-case flags:

Every key has four boolean flags that gate which endpoint categories it can access. The middleware rejects requests to any category the key does not permit.

A key with all flags false would authenticate successfully but be rejected at the use-case enforcement stage for every endpoint.

Lifecycle operations: All operations require a SaaS JWT with owner or admin role on the tenant.

Rotate vs Revoke vs Delete:

Limits:

The 3-key cap applies per tenant. Attempting to create a fourth key returns an error. Revoked keys still count toward the limit if the row is retained; use delete to free the slot.

Cache and invalidation: Validated keys are cached in Redis to avoid a database lookup on every request. Rotation and revocation both invalidate the cache entry immediately, so the old secret stops working as soon as the operation completes — there is no window where the old key remains valid after rotation.

Audit logging: All write operations (create, update, rotate, revoke, delete) are recorded in the tenant audit log. Tenant-owned key rotation is an in-place secret replacement on the same key ID. Subscriber key rotation creates a replacement row and links it to the previous row via rotatedFromId.

Limitations:

• Rate limits are fixed at creation. rateLimitPerMinute and rateLimitPerHour are not updatable after creation. To change rate limits, rotate or recreate the key.
• Plaintext is shown once. If the key value is lost after creation or rotation, the only recovery is to rotate the key and store the new value.
• expiresAt is stored but expiry is checked at validation time — there is no background job that auto-revokes expired keys.

Code references:

• Controller: GamersLabRestAPI/Saas/ApiKeys/Controllers/ApiKeysController.cs
• Service: GamersLabRestAPI/Saas/ApiKeys/Services/ApiKey/ApiKeyService.cs
• Key generator: GamersLabRestAPI/Saas/ApiKeys/Services/ApiKey/ApiKeyGenerator.cs
• Repository: GamersLabRestAPI/Saas/ApiKeys/Repositories/NpgsqlApiKeyRepository.cs
• Model: GamersLabRestAPI/Saas/ApiKeys/Models/TenantApiKey.cs
• Auth handler: GamersLabRestAPI/Saas/ApiKeys/Services/ApiKey/ApiKeyAuthenticationHandler.cs

4.1.2 Live Events Profiles

A live events profile is a JSON configuration that controls which events are streamed and how they are presented to a caller connected to a Server-Sent Events (SSE) endpoint. Every SSE connection resolves the effective profile for the requesting API key and applies its rules to each outbound event before it is written to the stream.

The API key must have allowLiveEvents = true to access SSE stream endpoints. The profile is referenced via liveEventsProfileId on the key.

Profiles are stored in bus_live_events_profiles. Each row holds the profile name, description, a profile_json blob containing the full configuration, and an is_system flag that protects platform-defined profiles from modification or deletion.

System profiles: Four system profiles are pre-defined and available to all tenants. They cannot be updated or deleted.

When no profile is configured for an API key and no tenant default is set, the platform selects the fallback system profile based on the API key's liveEventsScope setting (all, team, self, or none). This differs from historical data profiles, which always fall back to All.

Profile configuration fields: Every profile JSON object must include version (must be 1) and enabled (bool). All other fields are optional.

Stream types: The 7 recognized stream type keys:

Visibility levels: Used in visibilityByType. Stream types not listed in the map default to all.

Levels that require a player identity (self, team, match, registered, host) require the SSE connection to carry a valid player token. Connections using only an X-API-Key without a player token will not receive those stream types.

Delivery delays: delaysSeconds is a { streamType: int } map. When set for a stream type, the platform holds matching events for the specified number of seconds before writing them to the SSE stream. Values must be ≥ 0; negative values are rejected at save time.

Identity redaction: Identity redaction strips identifying fields from streamed event payloads.

• identityRedaction — applies globally to every stream type.
• identityRedactionByType — applies per stream type; merged with the global setting. Redaction can only be made more restrictive by overrides, never relaxed.

The four redactable fields for live events:

Live events identity redaction has a smaller surface than historical data profiles (4 fields vs 8) — session and device identifiers are not present in SSE payloads.

Event override lists: The overrides object controls which events are included in event-carrying stream types (matchEvents, playerEvents). All lists are case-insensitive and deduplicated on save.

Allow lists act as inclusive filters (only matching records pass). Deny lists are always evaluated after allow lists and always exclude matching records regardless of other settings.

Profile resolution order: For each SSE connection, the platform resolves the effective profile in this order:

1. The liveEventsProfileId on the API key (if set).
2. The tenant's default live events profile (stored in bus_tenants.default_live_events_profile_id).
3. The scope-mapped system profile based on the API key's liveEventsScope: none → None, self → Self, team → Team, all (or unset) → All.

If the resolved profile row cannot be found (e.g. deleted after assignment), the platform logs a warning and falls back to the scope-mapped system profile.

Override merging for subscriber keys: Subscriber and public API keys can carry additional profile overrides in their metadata (ApiKeyProfileOverrides.LiveEvents). When present, these overrides are merged on top of the resolved base profile:

• Overrides can only make visibility more restrictive, never more permissive.
• Identity redaction fields can only be enabled by an override, not disabled.
• Invalid override entries are logged as warnings and skipped.

Available operations: All operations require a SaaS JWT with owner or admin role on the tenant.

Caching: Two Redis cache entries are maintained per profile resolution (5-minute TTL each): live-events-profile:effective:{apiKeyId} and live-events-profile:tenant-default:{tenantId}. Both are invalidated on create, update, delete, and set-default operations.

Limitations:

• System profiles are immutable.
• Fallback depends on the key's scope setting — unlike historical data profiles (which always fall back to All), live events profiles fall back to the scope-mapped system profile.
• Version must be 1.
• Delay cannot be negative.
• 4 redactable fields only — session, device, and IP identifiers are not available in SSE payloads.
• Overrides can only restrict; subscriber key overrides cannot relax a base profile.
• 5-minute cache lag.

Code references:

• Controller: GamersLabRestAPI/Saas/ApiKeys/Controllers/LiveEventsProfilesController.cs
• Service: GamersLabRestAPI/Saas/ApiKeys/Services/LiveEventsProfileService.cs
• Model: GamersLabRestAPI/Saas/ApiKeys/Models/LiveEventsProfile.cs
• Stream types: GamersLabRestAPI/Saas/Business/Constants/LiveEventStreamTypes.cs
• Live events evaluator: GamersLabRestAPI/Game/Data/Services/LiveEventsProfileEvaluator.cs
• Override evaluator: GamersLabRestAPI/Saas/ApiKeys/Services/ProfileOverrideEvaluator.cs

4.1.3 Historical Data Profiles

A historical data profile is a JSON configuration attached to a tenant that controls which fields and data types are visible when a caller queries historical game data through read endpoints (e.g. match details, player stats, event records). Every historical data query resolves the effective profile for the requesting API key and applies its rules before returning data.

The API key must have allowDataApi = true to access historical data query endpoints. The profile is referenced via historicalDataProfileId on the key.

Profiles are stored in bus_historical_data_profiles. Each row holds the profile name, description, a profile_json blob, and an is_system flag that protects platform-defined profiles from modification or deletion.

System profiles: Four system profiles are pre-defined and available to all tenants. They cannot be updated or deleted.

When no profile is configured for an API key and no tenant default is set, the platform falls back to the All system profile.

Profile configuration fields: Every profile JSON object must include version (must be 1) and enabled (bool). All other fields are optional.

Data types: The 14 recognized data type keys:

Visibility levels: Used in visibilityByType. Types not listed in the map default to all.

Levels that require a player identity require the request to carry a valid player token. Requests using only an X-API-Key without a player token will be denied access to those data types.

Identity redaction: Removes or hashes identifying fields from responses.

• identityRedaction — applies globally to every data type.
• identityRedactionByType — applies per data type; merged with the global setting. Redaction can only be made more restrictive by overrides, never relaxed.

The eight redactable fields:

Event override lists: The overrides object controls which event records appear in event-returning data types (matchEvents, playerEvents). Same allow/deny list semantics as live events profiles — allow lists act as inclusive filters; deny lists are evaluated after allow lists.

Delay until match completed: historicalOptions.delayTillMatchCompletedByType is a { dataType: bool } map. When set to true for a data type, records of that type are withheld until the match is in a completed state.

Include host by type: includeHostByType is an array of data type keys. For listed types, the match host's data is always returned even when the visibility level would otherwise exclude it.

Profile resolution order:

1. The historicalDataProfileId on the API key (if set).
2. The tenant's default profile (stored in bus_tenants.default_historical_data_profile_id).
3. The All system profile (open access, no restrictions).

If the resolved profile row cannot be found, the platform logs a warning and falls back to the All system profile.

Override merging for subscriber keys: Same merging rules as live events profiles — overrides can only restrict, not relax. Invalid entries are logged and skipped.

Available operations: All operations require a SaaS JWT with owner or admin role on the tenant.

Caching: Two Redis cache entries (5-minute TTL each): historical-data-profile:effective:{apiKeyId} and historical-data-profile:tenant-default:{tenantId}. Both invalidated on create, update, delete, and set-default.

Limitations:

• System profiles are immutable.
• Fallback to All on missing profiles — if an API key references a deleted profile, the platform silently falls back to All. No error is returned to the caller.
• Version must be 1.
• Overrides can only restrict.
• No per-field visibility — visibility is controlled at the data-type level, not individual JSON field level. Use identity redaction for identity fields, event override lists for event records.
• 5-minute cache lag.

Code references:

• Controller: GamersLabRestAPI/Saas/ApiKeys/Controllers/HistoricalDataProfilesController.cs
• Service: GamersLabRestAPI/Saas/ApiKeys/Services/HistoricalDataProfileService.cs
• Model: GamersLabRestAPI/Saas/ApiKeys/Models/HistoricalDataProfile.cs
• Data types: GamersLabRestAPI/Core/Constants/HistoricalDataTypes.cs
• Historical evaluator: GamersLabRestAPI/Game/Data/Services/HistoricalDataProfileEvaluator.cs

Profile Type Comparison

Both profile systems share the same architecture and operations. The differences are in scope, type vocabulary, and a few feature-specific fields.

Feature comparison:

Identity redaction field coverage:

Historical data profiles expose more redactable fields because query responses include session and device data that SSE payloads do not.

System profile IDs:

Both use a 5-minute Redis TTL. Cache keys follow the same pattern with different prefixes. Operations (List, Get, Create, Update, Delete, Set Default) are identical for both and require a SaaS JWT with owner or admin role.

4.1.4 Rate Limiting

Per-key quota enforcement using Redis Lua scripts for atomic increment and check. Minute and hour counters with configurable limits. Returns 429 with Retry-After and X-RateLimit-Reset headers on exceeded limits.

Read key rate limits (per key):

• Default: 60 requests/minute, 1,000 requests/hour.
• Derived from tenant/company plan. Subscriber keys use subscriber plan limits when set.
• Per-key limits are capped by the plan ceiling.

Rate limit behavior:

• Exceeding limits returns HTTP 429 with Retry-After and X-RateLimit-Reset headers.
• Read rate limiting is fail-open by default, except for live/streaming paths which are fail-closed.
• Rate limits are adjusted via plan changes, not per-key edits.

4.1.5 Usage Tracking & Analytics

Every request authenticated with an X-API-Key is tracked by ApiKeyUsageTrackingMiddleware. Recording happens post-response — after the full pipeline has executed and the response has been written — so it has no impact on response latency from the caller's perspective.

Fields recorded per request to bus_api_key_usage:

Tracking can be suppressed for specific endpoints by setting HttpContextItemKeys.SkipApiKeyUsageTracking = true in HttpContext.Items.

Billing classification: Each recorded request is assigned a quota bucket and a billing outcome by UsageBillingClassifier.

Quota buckets:

Billing outcomes:

Only accepted requests consume billable units.

Analytics queries: All analytics endpoints require a SaaS JWT with owner or admin role on the tenant. Default window: last 30 days. Pagination: default 100, max 500.

Per-key analytics response includes:

Tenant-wide analytics response includes:

Daily usage returns a flat day-by-day breakdown (default last 90 days), optionally filtered to a single key:

Limitations:

• Post-response only. If the process crashes after writing the response but before the tracking call completes, that request's record is lost. Usage records are best-effort, not transactional.
• response_bytes depends on Content-Length. Streamed or chunked responses without a Content-Length header will have a null response_bytes value.
• rows_returned is not auto-populated. The field exists but is only set by controllers that explicitly write it to HttpContext.Items.
• No raw log access. The analytics endpoints return pre-aggregated views. Individual request records in bus_api_key_usage are not exposed through the API.

Code references:

• Middleware: GamersLabRestAPI/Saas/ApiKeys/Middleware/ApiKeyUsageTrackingMiddleware.cs
• Billing classifier: GamersLabRestAPI/Saas/Quota/Services/UsageBillingClassifier.cs
• Analytics controller: GamersLabRestAPI/Saas/ApiKeys/Controllers/ApiKeyAnalyticsController.cs
• Analytics service: GamersLabRestAPI/Saas/ApiKeys/Services/UsageAnalyticsService.cs
• Usage model: GamersLabRestAPI/Saas/ApiKeys/Models/ApiKeyUsage.cs

4.1.6 Middleware Pipeline

[NO DEDICATED DOC]

The API key middleware pipeline enforces three inbound stages for every X-API-Key request, then records usage after the response is produced:

1. Use-case enforcement — checks the key's boolean flags (allowDataApi, allowAuth, allowLiveEvents, allowActiveMatchData) against the requested endpoint's required use-case. A key that is missing the required flag is rejected even if it is otherwise valid and active.

2. Read-only enforcement — rejects non-read HTTP methods (POST, PUT, PATCH, DELETE) from a tenant API key except for the explicit hosted-auth allowlist: player JWT validation and third-party auth start/token/refresh endpoints. Those auth endpoints still require allowAuth = true.

3. Rate limit enforcement — checks the per-key Redis Lua atomic counters for the minute and hour windows. Returns 429 with Retry-After and X-RateLimit-Reset headers if the limit is exceeded. Fail-open by default (except live/streaming paths which are fail-closed).

4. Post-response usage tracking — after the response has been written, records the request to bus_api_key_usage with billing classification. This stage runs post-response and has no effect on response latency.

The pipeline is implemented as ASP.NET middleware components. HttpContext.Items is used to pass state between stages (quota bucket, billing outcome, skip-tracking flag).

Code references:

• Auth handler: GamersLabRestAPI/Saas/ApiKeys/Services/ApiKey/ApiKeyAuthenticationHandler.cs
• Usage tracking middleware: GamersLabRestAPI/Saas/ApiKeys/Middleware/ApiKeyUsageTrackingMiddleware.cs
• Middleware helper: GamersLabRestAPI/Core/Middleware/UsageTrackingMiddlewareHelper.cs