Give your AI agent a key, not your password.

1. Issue a key

Go to Agent keys, name it after the agent that will hold it, tick only the scopes it needs, and set an expiry. The key is shown once, so copy it straight away.

kg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Pick scopes

Scopes only ever narrow what you can already do. An agent can never reach a document you cannot reach yourself.

• READFetch documents the human can already see.Safe. Start here.
• WRITECreate documents and edit text.Cannot change who can see anything.
• SHAREChange visibility and invite people.The dangerous one. Grant only if you mean it.
• DELETERemove documents permanently.Irreversible. Rarely needed.

SHARE is never implied by WRITE. An agent that can write your documents still cannot publish them to the open web unless you explicitly allow it.

3. Use the API

Send the key as a bearer token. That is the whole integration, no SDK, no OAuth dance.

Create a page

curl -X POST https://kagoj.app/api/v1/documents \
  -H "Authorization: Bearer $KAGOJ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "MARKDOWN",
    "title": "Build notes",
    "source": "# Build notes\n\nAll green."
  }'

Returns { id, shortCode, url, title, visibility }. New pages default to link-only.

List what the key can read

curl https://kagoj.app/api/v1/documents \
  -H "Authorization: Bearer $KAGOJ_KEY"

Give it to a coding agent

Put the key in the agent’s environment and tell it the base URL. For a terminal agent, an env var is usually enough:

export KAGOJ_KEY="kg_live_..."
export KAGOJ_API="https://kagoj.app/api/v1"

There is also a machine-readable summary of Kagoj at /llms.txt that you can point an agent at.

4. Watch what it did

Every agent action is attributed to the key that performed it and listed on the Agent keys page. If something looks wrong, revoke the key, the next request it makes fails immediately.