KiwiFS supports four authentication modes. Choose the one that fits your deployment.
Auth modes
none (default)
apikey
perspace
oidc
No authentication. Suitable for local development and trusted networks. A single global API key protects all endpoints.[auth]
type = "apikey"
api_key = "kiwi_sk_your_secret_here"
curl http://localhost:3333/api/kiwi/tree \
-H "Authorization: Bearer kiwi_sk_your_secret_here"
Each space gets its own scoped API key with fine-grained permissions.[auth]
type = "perspace"
[[auth.api_keys]]
key = "kiwi_ro_eng_abc123"
space = "engineering"
actor = "eng-reader"
scope = "read"
prefix = ""
[[auth.api_keys]]
key = "kiwi_rw_eng_xyz789"
space = "engineering"
actor = "eng-writer"
scope = "write"
prefix = "concepts/"
[[auth.api_keys]]
key = "kiwi_admin_all"
space = ""
actor = "admin"
scope = "admin"
OpenID Connect for SSO via your identity provider.[auth]
type = "oidc"
[auth.oidc]
issuer = "https://accounts.google.com"
client_id = "your-client-id"
Auth configuration is hot-reloadable — send SIGHUP to the server process to reload from disk without restarting.
Per-space token fields
When using perspace auth, each [[auth.api_keys]] entry supports:
| Field | Required | Description |
|---|
key | Yes | The API key string (shown once on creation via CLI) |
space | No | Restrict to a specific space (empty = all spaces) |
actor | No | Default X-Actor value for git attribution |
scope | Yes | Permission level: read, write, or admin |
prefix | No | Restrict access to paths under this prefix |
Scopes
| Scope | Permissions |
|---|
read | GET endpoints only — tree, file, search, query, analytics |
write | Read + PUT, POST, DELETE on files, drafts, canvas, workflows |
admin | Write + space management, webhook CRUD, schema changes, audit log |
Managing tokens via CLI
The kiwifs token command creates and manages API keys stored in .kiwi/config.toml.
Create a token
kiwifs token create --root ./knowledge --space docs --scope read --actor ci-reader
Created API key: kiwi_ro_abc1deadbeef...
Space: docs | Scope: read | Actor: ci-reader
List tokens
kiwifs token list --root ./knowledge
PREFIX SPACE SCOPE ACTOR
kiwi_ro_abc1 docs read ci-reader
kiwi_rw_xyz7 engineering write eng-bot
kiwi_admin_a (all) admin admin
Revoke a token
kiwifs token revoke kiwi_ro_abc1
.kiwi/config.toml. Active requests with the revoked key are rejected on the next config reload.
Revoking a token does not require a server restart — KiwiFS watches the config file for changes.
Path-scoped access
Use the prefix field to restrict a token to a specific directory tree:
[[auth.api_keys]]
key = "kiwi_rw_agent_onboarding"
space = "engineering"
actor = "onboarding-bot"
scope = "write"
prefix = "onboarding/"
onboarding/. Requests to other paths return 401.
Cloud authentication
KiwiFS Cloud uses a separate authentication system:
- API key — pass
kiwi_sk_* as a Bearer token
- MCP OAuth 2.1 — browser-based login via WorkOS (PKCE)
kiwifs login # OAuth device flow
kiwifs whoami # Show current identity
kiwifs connect my-workspace --write cursor # Generate MCP config
~/.kiwifs/credentials.json.
See KiwiFS Cloud for details.
Configuration
Full auth config reference.
API overview
Auth headers and error codes.
Multi-space
Per-space routing and access control.
CLI commands
Token create, list, and revoke commands.
