Token Management¶
External API Token Lifecycle — Mandatory Expiry Tracking, Alerting, Manual Renewal, and Deployment
Document Version: 1.0.0
Last Updated: 2026-10-22
Since v1.0.60 — Enterprise Function (PoC / Enterprise license)
1. Overview¶
Many external systems — Jira, Signi, GitLab, payment gateways, SaaS APIs — issue long-lived API tokens that MazeVault cannot rotate automatically, because the only way to obtain a new token is to log in to the source system's own UI and generate one by hand. Such tokens tend to expire silently and break integrations.
Token Management gives these externally-issued tokens a managed lifecycle inside MazeVault:
| Feature | Description |
|---|---|
| Mandatory expiry | Every token must be registered with an expiration date; MazeVault tracks the days remaining |
| Expiry alerting | A token_expiry incident is raised before the token lapses and escalated to critical once it expires |
| Manual renewal | Record the newly obtained value and its new expiry in one step; the open incident is resolved automatically |
| Deployment targets | Deliver the token value to agent-managed config files, Kubernetes secrets, Azure Key Vault, or AWS Secrets Manager |
| Sync on renewal | Targets flagged for sync are re-deployed automatically after a renewal |
| Encrypted at rest | AES-256-GCM in standard mode; offloaded to the external secrets manager in Orchestrator Mode |
| Terraform support | mazevault_token resource and mazevault_tokens data source |
Token Management is available under Enterprise Functions → Token Management in the main menu.
How It Differs from Other Key Stores¶
| Store | Purpose | Where |
|---|---|---|
| Token Management | Externally-issued API tokens with manual renewal (Jira, Signi, …) | Enterprise Functions → Token Management |
| Project Key management | Project secrets (passwords, connection strings, generated keys) managed and rotated by MazeVault | Project → Secrets |
| System Keys | MazeVault's own infrastructure keys (encryption, signing, bootstrap) | Organization Settings → System Keys |
| User API tokens | Personal/service API tokens used to call the MazeVault API | User menu → API Tokens |
License Requirement
Token Management is gated by the token_management license feature, which is granted to PoC and Enterprise licenses (active, grace, or expiring state). On Small Business or unlicensed tenants the /api/v1/tokens API returns HTTP 403 and the page shows an upgrade banner. See Licensing.
2. Registering a Token¶
- Navigate to Enterprise Functions → Token Management
- Click Add Token
- Fill in the token details:
| Field | Required | Description |
|---|---|---|
| Name | ✅ | Unique display name, e.g. jira-automation-token |
| Provider | — | Free-text label of the issuing system (jira, signi, gitlab, …). Jira and Signi receive dedicated icons |
| Description | — | Purpose of the token |
| Value | ✅ | The token secret. It is encrypted immediately and never returned by list/detail endpoints |
| Expires at | ✅ | Expiration date and time as shown in the source system |
| Alert lead time (days) | — | How many days before expiry the alert opens. Default 30 |
| Project | — | Optional project binding. Project-bound tokens can be deployed to the project's agents and integrations |
| Metadata | — | Free-form key/value pairs (owner, ticket, cost centre, …) |
- Click Save
Expiry Date Is Mandatory
MazeVault cannot discover the expiry of an external token on its own. Copy the expiration date exactly as shown by the issuing system. If the system issues non-expiring tokens, set a policy-driven expiry (for example 12 months) so the token is still reviewed regularly.
Token Status¶
| Status | Meaning |
|---|---|
active |
Token is in use and monitored for expiry |
expired |
expires_at has passed; the incident is escalated to critical |
revoked |
Manually marked as revoked in the source system; excluded from monitoring |
Storage Mode¶
| Mode | Behaviour |
|---|---|
| Standard | The value is encrypted with AES-256-GCM and stored in the MazeVault database (storage_mode: local) |
| Orchestrator Mode | Only metadata is stored locally; the value is offloaded to the configured external secrets manager (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault) and the record carries storage_mode: external plus the external_provider_type |
3. Expiry Monitoring and Alerts¶
The notification scheduler evaluates every active token once a day:
| Condition | Result |
|---|---|
expires_at is more than lead time days away |
No action |
expires_at is within the lead window |
token_expiry incident opened (or refreshed) with severity high |
expires_at has passed |
Incident severity escalated to critical; token status becomes expired |
The incident is delivered through the standard incident notification path — incident contacts, email, webhook, Microsoft Teams, Slack, Jira, and SMSEagle integrations. See Notifications & Alerting.
The token list shows a colour-coded expiry chip (days remaining / expired) so operators can triage without opening each record.
Per-Token Lead Time
Use a longer lead time for tokens whose renewal requires an approval workflow or a third party (for example 60–90 days for partner-issued tokens).
4. Manual Renewal¶
When the token has been regenerated in the source system:
- Open the token and click Renew
- Paste the new value and enter the new expiration date
- Optionally add renewal notes (ticket number, who performed it)
- Click Renew
MazeVault then:
- Replaces the stored value (encrypted or offloaded) and records
last_renewed_at - Resets the status to
active - Resolves the open
token_expiryincident with the reason Token renewed - Re-deploys every deployment target that has Sync on renewal enabled
- Writes
TOKEN_RENEWto the audit log (andTOKEN_RENEW_SYNC_FAILEDfor any target that failed)
Renewal vs. Update
Update edits metadata only (name, description, provider, lead time, expiry date, status). Renew is the only operation that changes the token value.
5. Deployment Targets¶
A token can be delivered to the same target types as secrets. Deployment reuses MazeVault's shared value-delivery executors, so behaviour, auditing, and error handling match secret deployment.
| Target type | Description | Required configuration |
|---|---|---|
agent_file |
An agent-managed configuration file on a server. The token is written as a key → value entry | agent_id, target_path, file_format (json / yaml / env, default env), secret_key, optional post_install_cmd, backup |
kubernetes_secret |
A key inside a Kubernetes Secret | integration_id (Kubernetes integration), config.namespace, config.secret_name, config.key_name |
azure_keyvault |
A secret in Azure Key Vault | integration_id (Azure Key Vault integration), config.secret_name |
aws_secrets_manager |
A secret in AWS Secrets Manager | integration_id (AWS integration), config.secret_id, config.region |
Windows registry and IIS targets are intentionally not supported for tokens.
5.1 Agent Configuration File¶
The agent merges the token into an existing (or new) configuration file without touching other keys:
| Format | Example result |
|---|---|
json |
{ "jira": { "api_token": "<value>" } } for secret_key: jira.api_token |
yaml |
jira:\n api_token: <value> |
env |
JIRA_API_TOKEN=<value> |
Options:
- Backup — the agent keeps a timestamped copy of the previous file before writing
- Post-install command — executed after a successful write (for example
systemctl restart jira-sync). Only commands matching the agent's command allowlist are executed; see Agent Deployment → Command allowlist - Sync on renewal — automatically re-deploy after each renewal
5.2 Deployment Status¶
deployment_status |
Meaning |
|---|---|
pending |
Target created, first deployment not yet confirmed |
deployed |
Last sync succeeded (last_sync_at, last_sync_status) |
failed |
Last sync failed; error_message contains the reason |
Use Sync now on a target to retry a failed deployment or to push the current value immediately.
Project Binding
Deployment targets are resolved within the token's project. Changing or removing the project binding deletes the token's deployment targets.
6. Revealing a Token Value¶
The stored value is never included in list or detail responses. Users holding token:admin can reveal it from the token detail page (Reveal value). Every reveal is recorded as TOKEN_REVEAL in the audit log with the acting user.
7. Permissions¶
| Permission | Description | Built-in roles |
|---|---|---|
token:read |
View tokens, expiry status, and deployment targets | org_admin, operator, user, auditor |
token:write |
Create, update, renew tokens; add, remove, and sync deployment targets | org_admin, operator |
token:delete |
Delete tokens | org_admin, operator |
token:admin |
Reveal stored token values (implies write and deploy) | org_admin |
Users see the Token Management menu entry whenever they hold token:read; the license feature decides whether the page is functional. See RBAC Roles.
8. Audit Trail¶
| Audit action | Trigger |
|---|---|
TOKEN_CREATE |
Token registered |
TOKEN_UPDATE |
Metadata changed |
TOKEN_RENEW |
Value and expiry renewed |
TOKEN_REVEAL |
Value revealed by an administrator |
TOKEN_DELETE |
Token deleted |
TOKEN_TARGET_CREATE / TOKEN_TARGET_DELETE |
Deployment target added or removed |
TOKEN_DEPLOY / TOKEN_DEPLOY_FAILED |
Deployment to a target succeeded or failed |
TOKEN_RENEW_SYNC_FAILED |
Post-renewal re-deployment of a target failed |
TOKEN_INCIDENT_RESOLVE_FAILED |
Expiry incident could not be resolved after renewal |
TOKEN_OFFLOAD_CLEANUP_FAILED |
Offloaded external value could not be deleted (Orchestrator Mode) |
See Audit Logging.
9. Terraform¶
Tokens can be managed as code with the mazevault_token resource and listed with the mazevault_tokens data source — including the mandatory expires_at, lead_time_days, and write-only value_wo. Renewal of the value itself is done through the UI/API renew flow, not through Terraform. See Terraform Provider → External API Token Management.
10. Orchestrator Mode¶
In Orchestrator Mode the token value never resides in the MazeVault database. On create and renew the value is written to the organization's configured external secrets manager and only a reference is kept. Deleting the token removes the external value as well; a failure to do so is audited as TOKEN_OFFLOAD_CLEANUP_FAILED but does not block the deletion.
| Field | Value |
|---|---|
storage_mode |
external |
external_provider_type |
Scheme of the external reference (Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault, depending on the configured offload provider) |