API overview

Every tool internkim uses inside a company is callable from outside it, over HTTP, at https://api.intern.kim/v1. Every company calls that one address; the token is what says which company, and which person inside it. A token belongs to a person and every call runs as that person, so a token can never do more than its owner can.

One process terminates every /api/v1 request: admind. It authenticates the token, checks the scope, and forwards the work — tool calls to capabilityd over a unix socket, agent messages to the Blueclaw runtime over local HTTP. Nothing under /api/v1 executes a tool itself.

Getting a token

Tokens are issued from a signed-in staff web session, either through the token section on the Admin page or with the session cookie directly:

curl -X POST https://api.intern.kim/v1/tokens \
  --cookie "$SESSION" \
  --header 'Content-Type: application/json' \
  --data '{"label":"reporting script","scopes":["write"]}'

{
  "token": "ik_...",
  "actor": {
    "personID": "...",
    "email": "[email protected]",
    "displayName": "이샘플",
    "source": "public_api_token",
    "scopes": ["read", "write"]
  },
  "record": {
    "id": "tok_...",
    "label": "reporting script",
    "email": "[email protected]",
    "scopes": ["read", "write"],
    "createdAt": "2026-08-27T00:00:00Z"
  }
}

token is returned exactly once. The server keeps only a SHA-256 hash of it, in api-tokens.json under admind's state directory (/root/.internkim/state/admin by default). The owner is whoever the signed-in session belongs to; there is no way to issue a token for someone else.

Authentication

Every other endpoint takes the token as a bearer header:

curl https://api.intern.kim/v1/tools \
  --header "Authorization: Bearer $INTERNKIM_TOKEN"

The owner is re-resolved on every request. When the owner stops being active staff, every call with their token answers 403 from that moment on; nothing needs to be cleaned up first.

Scopes

read is always added to a token's scopes, whether requested or not. Requested scopes are lowercased, deduplicated, and anything unknown is silently dropped.

Authorization compares ranks, not scope names. A token's rank is the highest rank among its scopes; a tool's required rank comes from its sideEffectClass.

Three consequences worth knowing:

• Any rank-2 scope opens every rank-2 tool. A token issued with only connect can call message_send.
• admin grants nothing beyond what destructive grants.
• A descriptor with a sideEffectClass the gateway does not recognize requires rank 3. Unknown classes fail closed.

Errors

Success bodies are JSON. Error bodies are plain text.

Revoking a token

Every lookup skips records whose revokedAt is set, so revocation takes effect on the next request. No endpoint sets it yet: to revoke a token today, set revokedAt on its record in api-tokens.json and save the file.

The served reference

/api-docs on the same host serves an interactive reference, in Korean or English, rendered from an OpenAPI document at /openapi/<language>.json. The twenty-six base tools in that document are read from the same catalog the agent runs on.

Where it is implemented