Skip to content

Access protocol v1 ​

The shared server (kb-http) keeps no users and no passwords. It asks your system two questions over HTTP, through two webhooks you provide:

  1. Login — "here are a user name and a password (and later a code): give me a token".
  2. Permissions — "here is a token and the list of my projects: who is this, and which of these may they see?"

Everything else (who has which role, how the second factor works, how long a token lives) stays in your system. Your system needs to know nothing about the KB's configuration: it gets the project names in the question and answers with a subset of them, or "*" for all.

Both webhooks take and return JSON. Every request carries "protocol": 1 and the headers in KB_HOOK_HEADERS (a JSON object, for example {"X-Client": "kb"}), so your system can tell the KB's calls apart.

1. Login webhook — KB_LOGIN_URL ​

Used by the browser sign-in of MCP clients, by the admin pages and by kb-login.

Step 1: the password

http
POST {KB_LOGIN_URL}
Content-Type: application/json

{"protocol": 1, "username": "ann", "password": "…"}
AnswerMeaning
200 {"token": "…"}signed in; the token is what the KB sends to the permission webhook
200 {"two_factor": {"challenge": "…"}}a second step is needed: ask for the code
401 or 422 {"message": "…"}refused; the message is shown to the person
429 with Retry-Aftertoo many attempts

Step 2: the code (only after a two_factor answer)

http
POST {KB_LOGIN_URL}

{"protocol": 1, "challenge": "…", "code": "123456"}

code is whatever the person typed: an authenticator code or a recovery code; your system decides. Answers as in step 1, without another two_factor.

A person who first has to set up an authenticator should do it in your own app: answer 401 {"message": "set up the authenticator in the app first"}.

2. Permission webhook — KB_PERMISSION_URL ​

Asked for every request with an unknown token, then cached for KB_AUTH_CACHE_SECONDS (60) per SHA-256 of the token. The token itself is never logged.

http
POST {KB_PERMISSION_URL}
Authorization: Bearer <token>
Content-Type: application/json

{"protocol": 1, "projects": ["api", "web", "admin"]}
AnswerMeaning
200 {"user": {"name": "ann", …}, "projects": ["api", "web"]}these projects; names not in the question are ignored
200 {"user": {…}, "projects": "*"}every project of the question
401the token is unknown or expired: the client signs in again
403, or 200 with an empty listthe person may not use the KB
unreachable, or a body of another shape503, not cached

user may hold any fields; the KB shows the first of name, uname, username, id, uid in its logs and admin pages, and matches KB_ADMINS against them.

The smallest implementation ​

A team without an API of its own can answer both webhooks from a short script. An example in Python with one shared password and a fixed project list per user:

python
# hooks.py — run behind your TLS proxy; tokens live in memory for the demo
import json, secrets
from http.server import BaseHTTPRequestHandler, HTTPServer

USERS = {"ann": ("password-of-ann", "*"), "bob": ("password-of-bob", ["web"])}
TOKENS = {}

class Hooks(BaseHTTPRequestHandler):
    def answer(self, status, body):
        data = json.dumps(body).encode()
        self.send_response(status); self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(data))); self.end_headers(); self.wfile.write(data)

    def do_POST(self):
        body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        if self.path == "/login":
            user = USERS.get(body.get("username"))
            if not user or not secrets.compare_digest(user[0], body.get("password", "")):
                return self.answer(401, {"message": "wrong user name or password"})
            token = secrets.token_urlsafe(32)
            TOKENS[token] = body["username"]
            return self.answer(200, {"token": token})
        if self.path == "/permissions":
            name = TOKENS.get(self.headers.get("Authorization", "")[7:])
            if not name:
                return self.answer(401, {"message": "unknown token"})
            return self.answer(200, {"user": {"name": name}, "projects": USERS[name][1]})
        self.answer(404, {})

HTTPServer(("127.0.0.1", 8791), Hooks).serve_forever()
bash
KB_SERVER=on KB_LOGIN_URL=http://127.0.0.1:8791/login \
  KB_PERMISSION_URL=http://127.0.0.1:8791/permissions kb-http

Settings ​

VariableMeaning
KB_PERMISSION_URLthe permission webhook (required for kb-http)
KB_LOGIN_URLthe login webhook (browser sign-in, admin pages, kb-login); without it only ready tokens work
KB_HOOK_HEADERSextra headers for both webhooks, a JSON object
KB_AUTH_CACHE_SECONDShow long an answer of the permission webhook is kept (60)
KB_AUTH_TIMEOUTthe timeout of a webhook call in seconds (10)

AGPL-3.0-or-later