Authentication and tokens

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.

.kiwi/config.toml

[auth]
type = "none"

A single global API key protects all endpoints.

.kiwi/config.toml

[auth]
type = "apikey"
api_key = "kiwi_sk_your_secret_here"

Pass the key as a Bearer token:

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.

.kiwi/config.toml

[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.

.kiwi/config.toml

[auth]
type = "oidc"

[auth.oidc]
issuer = "https://accounts.google.com"
client_id = "your-client-id"

Clients pass a JWT Bearer token from the identity provider.

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

The plaintext key is displayed once. Copy it immediately — it cannot be retrieved later.

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

Revocation removes the key from .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/"

This token can only read and write files under 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

Cloud credentials are stored at ~/.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.

Getting Started

Core Concepts

Guides

Data Import

Data Export

Deployment

Auth modes

Per-space token fields

Scopes

Managing tokens via CLI

Create a token

List tokens

Revoke a token

Path-scoped access

Cloud authentication

Configuration

API overview

Multi-space

CLI commands

​Auth modes

​Per-space token fields

​Scopes

​Managing tokens via CLI

​Create a token

​List tokens

​Revoke a token

​Path-scoped access

​Cloud authentication

​Related documentation

Configuration

API overview

Multi-space

CLI commands

Auth modes

Per-space token fields

Scopes

Managing tokens via CLI

Create a token

List tokens

Revoke a token

Path-scoped access

Cloud authentication

Related documentation