License Management & Feature Gating
Understand what your license covers, monitor expiration, and take action before service is interrupted.
Requires role: Viewer (status check), Admin (settings context)
Related: User Management & RBAC, Multi-Agent Intelligence, Select Fire
Overview
Every FidelID™ deployment requires a valid license. The license controls three things:
- Which features are active — The AI Intelligence tier unlocks natural language queries, risk-quantified remediation scripts, and predictive provisioning (coming soon). Deployments without this tier still have full access to the identity graph, risk posture dashboard, simulation, and all analytics.
- How many identities can be managed — The license specifies a maximum identity count that matches your contracted deployment size.
- How long the license is valid — Licenses are time-bound. The platform monitors expiration continuously and stops serving requests when the license expires.
The license is validated at startup and checked every hour at runtime. If it expires while the server is running, the platform gracefully stops accepting new requests — existing in-progress operations complete, but no new work is accepted until a valid license is applied.
IMPORTANT
Infrastructure probes (/health, /ready) and the Prometheus metrics endpoint (/metrics) remain available even after license expiration, so your monitoring and orchestration systems are not affected.
License Tiers
GraphnAI offers two feature tiers, plus a time-limited trial:
| Tier | Who it's for | What's included |
|---|---|---|
| Free Trial / PoC | Prospects evaluating the platform | Graph topology, risk posture dashboard, stale identity detection, over-permission analytics, simulation, path analysis. No AI features. |
| Design Partner | Early customers collaborating on product direction | Everything in the trial, plus AI Intelligence: Graphne conversational agent, natural language graph queries, AI-driven remediation recommendations. |
| Paid | Production deployments | Everything in Design Partner, with a higher identity cap appropriate for production scale. |
The presence or absence of the AI Intelligence feature (ai_agent) in your license determines which tier you are on.
Prerequisites
- You must be logged in with at least a Viewer role to check license status.
- No additional configuration is needed — license status is available as soon as the server starts with a valid license.
Checking License Status
Any authenticated user can view the current license status. This is the primary way to confirm what features are active, how many identities are in use, and how many days remain before renewal is needed.
License status fields
| Field | Description |
|---|---|
tenantId | Your organization's identifier as issued by GraphnAI. |
features | List of feature flags active on this license. An empty array means visibility-only tier (no AI features). |
maxIdentities | The maximum number of identities your license covers. A value of 0 means no cap is configured. |
currentIdentities | The number of identities currently stored in the graph. Updated at sync time. |
expiresAt | License expiration date in ISO 8601 format. |
daysRemaining | Whole days until expiration, rounded up. Returns 0 once the license is expired. |
expired | true if the license has already expired. When this is true, the expiry watcher has already blocked new requests. |
What a visibility-only license looks like
A trial or PoC license without AI features returns an empty features list. The currentIdentities field reflects how many identities are currently synced compared to the maxIdentities cap. If currentIdentities is approaching maxIdentities, plan for renewal or a tier upgrade before the cap is reached.
Feature Gating: AI Intelligence
AI Intelligence features — the Graphne conversational agent, natural language queries, risk analysis, remediation scripts, and predictive provisioning (coming soon) — require the ai_agent feature flag in your license.
When this flag is absent and an AI feature is requested, the platform returns an explicit error identifying exactly which feature is missing and why. This response is intentional: the platform does not silently hide AI features — it tells you exactly what is missing so you know what to ask about when evaluating an upgrade.
All analytics, graph, simulation, and bridge features are available on all license tiers — only AI Intelligence requires the ai_agent flag.
UI behavior (planned)
The license-aware UI is planned for the MVP release. When implemented, the AI Intelligence features will be visible in the interface but shown with a lock icon and a contextual message explaining the upgrade path — rather than being hidden entirely.
Identity Cap
Your license specifies a maxIdentities limit that corresponds to your contracted deployment size.
How the cap works
The identity cap is currently a soft cap. When a directory sync completes and the identity count exceeds the licensed maximum, the platform:
- Logs a warning in the server logs, identifying the current count and the licensed maximum.
- Increments the
graphnai_license_identities_currentPrometheus metric so you can alert on the condition. - Allows the sync to complete — existing data is preserved and no identities are rejected.
The sync does not fail and no data is lost. The purpose of the warning is to give you time to either clean up stale identities or contact your account manager to upgrade your identity count before the next contracted review.
NOTE
A configurable hard cap — which would reject new identities beyond the licensed limit at ingestion time — is planned for a future release. The current behavior is intentionally soft to avoid mid-sync failures caused by discovering unexpectedly large directories during a first sync.
Checking current usage
The currentIdentities and maxIdentities values are visible in the license status. If the current count is approaching the maximum, plan for renewal or a tier upgrade before the cap is reached.
Expiration Behavior
What happens when a license expires
The platform runs an hourly background check against the license expiration date. When the license expires:
- The server logs a warning identifying the expiration time and tenant.
- All new authenticated requests are blocked with an HTTP 503 response indicating the license has expired and prompting you to contact your account manager.
- Requests that were already in progress complete normally — nothing is interrupted mid-flight.
- Background workers (sync jobs, analytics pipeline) stop accepting new work but finish any task that is already running.
- Identity Bridge connections are maintained — bridges continue collecting directory data, but sync finalization will be blocked until the license is renewed.
What stays available after expiration
| Endpoint | Available after expiration |
|---|---|
/health | Yes — liveness probe always responds |
/ready | Yes — readiness probe always responds |
/metrics | Yes — Prometheus scrape target always available |
| Login | Yes — so admins can log in to check status |
| License status | Yes — so you can confirm expiration details |
| All other platform features | No — returns HTTP 503 until renewed |
This design ensures your orchestration system (Kubernetes, load balancer health checks) continues working correctly, and your monitoring systems continue scraping metrics. You can still log in to review status without needing direct server access.
Applying a renewed license
Currently, applying a new license requires a server restart. When your account manager issues a renewed license:
- Update your license key setting with the new license value provided by your account manager.
- Restart the
graphnai-servercontainer or process. - The server validates the new license at startup. If valid, it starts normally and all endpoints become available again.
- Confirm the renewal by checking the license status and verifying the new expiration date and days remaining.
NOTE
Hot-reload of license keys without a restart is planned for a future release.
Prometheus Metrics
The platform exposes four license-related metrics at the /metrics endpoint. These are set at startup and updated during the hourly expiration check.
| Metric | Type | Description |
|---|---|---|
graphnai_license_expires_at | Gauge | License expiration as a Unix timestamp. Use this with time() to compute time-to-expiry in alerting rules. |
graphnai_license_identities_max | Gauge | Maximum identities allowed by the license. 0 means no cap is configured. |
graphnai_license_identities_current | Gauge | Current identity count. Updated each time a sync completes. |
graphnai_license_feature_enabled{feature="ai_agent"} | Gauge | 1 if the ai_agent feature is active on the license, 0 if not. |
Recommended alerting rules
The following Prometheus alerting rules cover the most common license monitoring scenarios. Adapt thresholds to your organization's renewal lead time.
Alert when the license expires in 30 days or fewer:
yaml
- alert: LicenseExpiringSoon
expr: (graphnai_license_expires_at - time()) < 86400 * 30
for: 1h
labels:
severity: warning
annotations:
summary: "GraphnAI license expires in less than 30 days"
description: "License expires at {{ $value | humanizeTimestamp }}. Contact your account manager to renew."Alert when the license expires in 7 days or fewer:
yaml
- alert: LicenseExpiringCritical
expr: (graphnai_license_expires_at - time()) < 86400 * 7
for: 15m
labels:
severity: critical
annotations:
summary: "GraphnAI license expires in less than 7 days"
description: "Service will be interrupted upon expiration. Renew immediately."Alert when the identity count exceeds the licensed cap:
yaml
- alert: IdentityCapExceeded
expr: graphnai_license_identities_current > graphnai_license_identities_max and graphnai_license_identities_max > 0
for: 5m
labels:
severity: warning
annotations:
summary: "Identity count exceeds license cap"
description: "{{ $value }} identities synced, cap is {{ $labels.max }}. Contact your account manager."Troubleshooting
All API requests return HTTP 503
Cause: The license has expired. The hourly background check detected the expiration and blocked new requests.
Resolution:
- Navigate to the license status page — this remains accessible after expiration. Confirm the expired status and note the expiration timestamp.
- Contact your GraphnAI account manager with your tenant ID to obtain a renewed license.
- Update your license key setting with the renewed license value and restart the server.
AI features are blocked with a "feature not licensed" error
Cause: The ai_agent feature is not included in your license. This is expected behavior for trial and visibility-only licenses.
Resolution: Check the features list in the license status. If ai_agent is absent and you believe it should be included, contact your account manager. If you are evaluating the AI tier, ask about a Design Partner or full platform license.
Server logs show "Identity count exceeds license limit" after sync
Cause: The number of identities discovered during a sync exceeds the maxIdentities value in your license. This is a warning, not an error — the sync completes and data is preserved.
Resolution: Review the currentIdentities and maxIdentities values in the license status. Options:
- Remove stale identity data by cleaning up inactive identities in your directory and running another sync.
- Contact your account manager to upgrade your identity cap.
The graphnai_license_identities_current Prometheus metric will reflect the post-sync count, so the condition is also visible in your metrics dashboard.
Server refuses to start with "license expired" or "invalid license"
Cause: The license key setting contains an expired or malformed license.
Resolution: Obtain a valid license from your account manager. The license is a signed token — do not modify it. Set the full license key value in your server configuration (or write it to the path referenced by your file-based secrets setting if using Docker Secrets) and restart the server.
License status shows "License not configured"
Cause: The server started without a license key configured. This should not occur in production deployments; it typically indicates a missing environment variable or secrets injection failure.
Resolution: Verify the license key environment variable is set and accessible to the server process. For Docker Secrets, confirm the _FILE suffix variant is configured correctly and the secret file exists at the referenced path.