API-key authentication and session model

The YouTeacher MCP server authenticates to the platform with an Ed25519 API key the owner generates in the web UI. The private key stays on the owner's machine and is never sent over the wire. This node describes how that key becomes a working, self-refreshing session, and how one MCP process satisfies the backend's two-layer auth.

Two identities on every cross-service call

The backend distinguishes two things about a request: who the user is, and which platform component is making the call. A call that crosses service boundaries therefore needs both a user session and a service-level credential. The MCP server's only stored credential is its key: it proves user identity by signing a challenge, and proves platform identity with a short-lived service token it signs afresh for each request.

Sign a challenge, exchange it for a session

On the first authenticated call the server signs a short-lived challenge with its private key and presents it, alongside the key id, to a dedicated sign-in-by-key endpoint on the auth service. Auth verifies the signature against the registered public key and returns a session. The session is cached in memory together with the material needed to mint service tokens; nothing is written to disk, so a process restart simply re-signs from scratch.

Refresh is transparent

Every authenticated call goes out carrying the cached session. If the backend rejects it as unauthorized, the server drops the cached session, signs a fresh challenge, and retries once. Two cases flow through the same path: a naturally expired session heals silently on the retry, while a genuinely revoked key fails the retry and the error surfaces to the caller. Sessions use the same long-lived window as an ordinary login.

Revocation

Revocation cascades: revoking a key in the UI invalidates every session derived from it at once, so a lost machine loses access immediately.

Onboarding shape

The owner generates a key in the account security page, downloads the private key once (it is shown a single time), and stores it in a local credentials file that also records the target environment. The MCP client is pointed at that file by an environment variable; one key belongs to one environment.