Token handling

Storage

• On your workstation: token in ~/.knowmind/config.json with chmod 600 (Unix) or equivalent ACLs (Windows). The knowmind CLI sets this automatically.
• In CI pipelines: as an encrypted variable in GitHub Actions, GitLab CI or equivalent. Pass it as an environment variable in the workflow:

# GitHub Actions example
env:
  KNOWMIND_TOKEN: ${{ secrets.KNOWMIND_TOKEN }}

• In container environments: as a secret volume or through your orchestration's secret management (Kubernetes Secrets, Docker Compose secrets).
• In server applications: from a secret backend of your choice (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password Secrets Automation). Do not store in configuration files.

Token granularity

• One token per device. If a laptop is lost, you can revoke specifically the laptop's token.
• One token per application. The audit log then tells you which app caused which action.
• Minimum required scope. If the app only reads, use read. Only add write where you actually write.
• Optionally set an expiry. For short-lived setups (demo, test) this devalues forgotten tokens automatically.

Rotation

1. Create a new token with the same name pattern and scope (see Create an API token).
2. Push the clear text into the secret backend or update the consuming application's configuration.
3. Restart the application and verify the new token works.
4. Revoke the old token in the dashboard. The audit log records the revocation with timestamp.

Recommendation: rotate every 90 days. In regulated industries (finance, health) more often, per your internal policy.

Compromise response

1. Immediately revoke the affected token in the dashboard.
2. In the audit log under Security log, check the recent actions — which calls ran on this token.
3. On signs of unwanted activity (unknown IP, unusual endpoints), document the incident and assess under GDPR Art. 33 whether to notify the supervisory authority.
4. If needed, also review the OAuth connections under Dashboard → OAuth Clients and remove any unknown connectors.
5. Create a new token with the same scope, deploy it to the consuming application, document the procedure.