Authentication and tokens

KiwiFS has no authentication by default, which suits a laptop or a trusted network. Before you expose a server, pick an auth mode in [auth] of .kiwi/config.toml. Every mode uses the same header:

Terminal

curl http://localhost:3333/api/kiwi/tree \
  -H "Authorization: Bearer $KIWI_TOKEN"

Auth modes

none (default)
apikey
perspace
oidc

No authentication.

.kiwi/config.toml

[auth]
type = "none"

One shared key for every request. Use ${ENV_VAR} to keep the secret out of the file.

.kiwi/config.toml

[auth]
type = "apikey"
api_key = "${KIWI_API_KEY}"

Or from the command line: kiwifs serve --auth apikey --api-key "$KIWI_API_KEY".

Many keys, each with its own scope, space, path prefix, and actor name.

.kiwi/config.toml

[auth]
type = "perspace"

[[auth.api_keys]]
key = "kiwi_ro_..."
actor = "ci-reader"
scope = "read"

[[auth.api_keys]]
key = "kiwi_rw_..."
actor = "onboarding-bot"
scope = "write"
prefix = "onboarding/"

[[auth.api_keys]]
key = "kiwi_adm_..."
actor = "admin"
scope = "admin"

Create keys with kiwifs token create instead of writing them by hand.

Accept ID tokens from your identity provider.

.kiwi/config.toml

[auth]
type = "oidc"

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

Clients send the provider’s JWT as the bearer token. KiwiFS records the token’s email claim (or sub) as the actor in git commits. Command-line equivalent: --auth oidc --oidc-issuer ... --oidc-client-id ....

A request without a valid token returns 401. A valid token used outside its scope, space, or prefix returns 403.

Per-space token fields

Each [[auth.api_keys]] entry supports:

Field	Default	Description
`key`	—	The secret the client sends as a bearer token
`scope`	`admin`	`read`, `write`, or `admin`
`space`	all spaces	In multi-space mode, the only space that accepts this key
`prefix`	none	Restrict the key to paths under this prefix
`actor`	—	Name recorded as `X-Actor` in git commits and the audit log

A key with no scope gets admin. kiwifs token create defaults to read, so set scope explicitly when you write entries by hand.

Scopes

Scope	Can do
`read`	`GET` and `HEAD` requests only. Any other method returns `403`.
`write`	All read and write requests
`admin`	Everything

Path prefixes

A prefix limits every request that names a path, including each file in a POST /api/kiwi/bulk body:

.kiwi/config.toml

[[auth.api_keys]]
key = "kiwi_rw_..."
actor = "onboarding-bot"
scope = "write"
prefix = "onboarding/"

This key can read and write onboarding/welcome.md. A request for ?path=pages/secret.md returns 403 path outside token prefix scope.

Manage tokens with the CLI

kiwifs token edits [[auth.api_keys]] in .kiwi/config.toml. If [auth] type is unset or none, token create switches it to perspace.

Create a token

Terminal

kiwifs token create --root ./knowledge --scope write --prefix docs/ --actor docs-bot

Output

Token created successfully. Save this key — it will not be shown again.

  Key:    kiwi_rw_3f9c...
  Scope:  write
  Prefix: docs/
  Actor:  docs-bot

Use: Authorization: Bearer kiwi_rw_3f9c...

Reload the server (SIGHUP or restart) for the new token to take effect.

Keys start with kiwi_ro_, kiwi_rw_, or kiwi_adm_ depending on scope. Flags: --space, --scope (default read), --prefix, --actor (default <scope>-token), --root.

Reload the server

Terminal

kill -HUP $(pgrep -f "kiwifs serve")

SIGHUP reloads [auth] from disk without dropping in-flight requests. Port and storage changes still need a restart.

List and revoke

Terminal

kiwifs token list --root ./knowledge
kiwifs token revoke kiwi_rw_3f9c --root ./knowledge

list shows the first 12 characters of each key with its scope, space, actor, and prefix. revoke removes every key that starts with the prefix you give. Send SIGHUP again to make the revocation take effect.

KiwiFS doesn’t watch config.toml for auth changes. Created and revoked tokens only take effect after SIGHUP or a restart.

Public and unlisted spaces

Set [space] visibility to open read access without a token:

Visibility	Unauthenticated access
`private` (default)	None
`unlisted`	`GET` of a single file by path (`/file`, `/peek`, `/section`). Tree, search, and listings still need a token.
`public`	All `GET` requests

Writes always need a token. Change visibility at runtime with PUT /api/kiwi/space/visibility.

Raw files and llms.txt

Two routes sit outside /api/kiwi so browsers and crawlers can reach them. When auth is on:

/raw/{path} serves a file only with an Authorization header (checked against the key’s space and prefix), a signed URL, or when the file is already public: a page with visibility: public or published: true, an asset next to such a page, or the configured logo and favicon.
/llms.txt and /llms-full.txt list only public or published pages, unless the whole space is public.

<img> and <video> tags can’t send headers, so get a signed URL instead. The web UI does this automatically.

Terminal

curl 'http://localhost:3333/api/kiwi/raw-sign?path=assets/diagram.png' \
  -H "Authorization: Bearer $KIWI_TOKEN"

Response

{
  "path": "assets/diagram.png",
  "url": "/raw/assets/diagram.png?exp=1792400400&sig=...",
  "expires": "2026-10-19T15:00:00Z"
}

Signed URLs last 30 to 60 minutes and stop working when the server restarts.

Other protocols

REST honors every auth mode. The other surfaces check only the global api_key:

Surface	Auth
REST `/api/kiwi/*`	All modes
MCP over HTTP (`/mcp`, or `kiwifs mcp --http`)	Bearer `api_key` in `apikey` mode
S3, WebDAV	Bearer (WebDAV also Basic) `api_key` in `apikey` mode
NFS	IP allowlist only (`--nfs-allow`)

With perspace or oidc, the MCP HTTP endpoint, S3, and WebDAV don’t require a token. Don’t enable --s3 or --webdav on a public network in those modes, and keep /mcp behind a proxy that authenticates.

To point the MCP bridge or a FUSE mount at a protected server, pass a token:

Terminal

kiwifs mcp --remote https://wiki.example.com --api-key "$KIWI_TOKEN"
kiwifs mount --remote https://wiki.example.com --bearer "$KIWI_TOKEN" ~/wiki

CORS

With auth off, the API only answers cross-origin browser requests from localhost. With auth on, any origin is allowed until you list the ones you trust:

.kiwi/config.toml

[server.cors]
allowed_origins = ["https://app.example.com"]

Configuration

Every config.toml key.

API overview

Headers and error codes.

Multi-space

Serve several knowledge bases from one server.

Publishing

Make individual pages public.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

Auth modes

Per-space token fields

Scopes

Path prefixes

Manage tokens with the CLI

Public and unlisted spaces

Raw files and llms.txt

Other protocols

CORS

Configuration

API overview

Multi-space

Publishing

​Auth modes

​Per-space token fields

​Scopes

​Path prefixes

​Manage tokens with the CLI

​Public and unlisted spaces

​Raw files and llms.txt

​Other protocols

​CORS

​Related

Configuration

API overview

Multi-space

Publishing

Auth modes

Per-space token fields

Scopes

Path prefixes

Manage tokens with the CLI

Public and unlisted spaces

Raw files and llms.txt

Other protocols

CORS

Related