Tasks

Create an API token

An API token authenticates calls to the knowmind APIs — from the command line, from custom connectors or from your own applications. Tokens carry scopes (read, write, admin) and are shown in clear text only once.

Audience

Power users and developers. API tokens are available on every plan, including the free Privat tier. If you would rather not handle a token, the supported AI tools also offer the OAuth path through the browser UI.

Prerequisites

knowmind account (any plan, including the free Privat tier)
Clear purpose (e.g. workstation, CI pipeline, MCP connector)
A secure buffer for the token (password manager, vault, encrypted CI variable)

Safety notice

One token, one purpose

Create a token per device, per application and per CI pipeline. If one is compromised you revoke only that one, the rest keeps running. Use the minimum required scope — read for read-only, write only where you actually create content.

Steps

1
Open the token area
In the dashboard click API Tokens (in the header navigation under "Integrations").
Outcome: You see the list of existing tokens with name, scope, last use and a revoke button.

Create the token

Click "New token". In the form:

Field	Recommendation
Name	Descriptive, e.g. "Anna's workstation" or "GitHub Actions build"
Scopes	`read` for recall; additionally `write` for store, upload, link; `admin` for plan-relevant actions
Expiry	Optional — when set, the token is auto-invalidated

Click Create.

3
Copy the token immediately
The token appears in the form kmt_… with a copy button. Copy and store it securely now — once the dialog closes only the prefix and a hash remain.
text
```
kmt_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789-AbCdEfGhIjK
```
Outcome: The token is in your password manager or CI vault. In the dashboard it appears in the list with its prefix.

Put the token to work

Examples:

bash

# Command line
knowmind login --token kmt_…

# Environment variable (CI, containers)
export KNOWMIND_TOKEN="kmt_…"

# In an HTTP request
curl -H "Authorization: Bearer kmt_…" https://knowmind.de/api/health

Verify the result

The dashboard API Tokens list shows the new entry with its prefix and creation date.
The audit log records "API token created".
A test call (knowmind health or a curl /api/health) returns a success message.

Troubleshooting

Error message	Cause	Resolution
Request rejected with 402 or 403	No valid token in the Authorization header, or the plan's rate limit is exceeded (Private 30, Pro 60, Team 120, Business 120, Enterprise 600 requests per minute). The plan itself never blocks API access — it is available on every plan, including the free Private tier.	Check the token value (complete, not expired, not revoked) and set it correctly as a Bearer. On 429/rate-limit, wait briefly or move to a plan with higher throughput.
Token dialog shows only "•••••" instead of a value	The dialog was closed once — the clear text is gone.	Revoke the token and create a new one. Copy the clear text immediately next time.
Token accepted on /api/health but rejected with 403 on /api/v1/memory/entries	Scope write is missing.	Edit the token to add the write scope, or create a new token with all required scopes.
"Last used" stays empty despite use	"Last used" updates with a slight delay (up to one minute).	Wait briefly and reload. If consistently empty, check the audit log — every successful call is recorded there.