Cross-Service Agent Integration: Minting a User-Level JWT, JWKS Signature Verification, the inject/memory/usage Interfaces, Idempotent externalId
Connect the mini-multi-agent service to mini-koda: mint a user-level JWT, verify signatures with JWKS, and integrate the inject, memory, and usage interfaces while guaranteeing idempotency.
Today's Goals
- Implement a user-level JWT minting flow, and explain how it differs from a service-level token
- Implement JWKS signature verification to validate a cross-service request's legitimacy
- Integrate the inject/memory/usage interfaces, guaranteeing idempotency with an externalId
Yesterday's graph runs to completion, compresses history, and resumes from a checkpoint. It is still an island: every input comes from a sentence you fed in by hand. Today connects it to W2's agent platform — the first time this course's two milestone projects join up.
Plain-Language Walkthrough
Abroad on business, you present your own passport
Set out the two ends being connected. W2's mini-koda is an agent platform: it has sessions, execution records, long-term memory, and a cost ledger, and the user's data lives with it. W3's multi-agent orchestration service is another process, another repository, managed by another team, and after running a round of triage and a refund draft it needs to write its conclusion back into the user's session and read what that user said before.
So the question becomes: on what basis do two services trust each other?
The easiest answer is issuing a key. The platform generates a long random string and hands it to the orchestration service, which includes it on every request, and the platform compares and admits. That is a service-level token, and it is what most teams ship in their first version. Its problem is not insecurity, it is that once something goes wrong you have no remedy at all.
Recast it as traveling abroad and it is obvious. A service-level token is B country issuing one master key to a company in A country: whoever holds it can walk into any office and pull any file. The normal arrangement has each person enter on their own passport, with border control checking who this person is, why they came, and when the visa expires.
A user-level token is that passport. It is issued by the orchestration service and represents one specific user, carrying that user's id and what they may do this time. Three reasons make it mandatory rather than merely tidier:
First, blast radius. One service-level token leaking exposes every user's data at once, and you cannot even tell where the leak came from; one user-level token leaking loses one user's data at most, and it expires by itself in fifteen minutes.
Second, the audit cannot reach a person. In a post-mortem you can only find that the orchestration service called a write endpoint at 03:14, not on whose behalf. With a sub claim, every access log lands on a specific user.
Third, the downstream cannot make user-level permission decisions. The platform's memory endpoint must answer whose memory to return, and if identity can only be read from the request body then that question is handed to the caller — and a caller can be wrong, and can lie.
So what belongs in that passport? Far less than most people think. A JWT's payload is base64-encoded, not encrypted, and anybody holding a token can open it and read:
eyJhbGciOiJSUzI1NiIsImtpZCI6ImFnZW50LWtleS0xIn0.eyJzY29wZSI6...
| decode the middle base64 segment, no key required
{
"sub": "u-1",
"iss": "http://127.0.0.1:4019",
"aud": "mini-koda",
"scope": "inject:write memory:read",
"jti": "5968-2b94-2db3-4fe0",
"iat": 1788566547,
"exp": 1788567447
}This course fixes those five claims (plus issued-at and expiry): sub is the user id, iss is who signed it, aud is who it was signed for, scope is what this authorization permits, and jti is the token's own number. No business data whatsoever. Two hard reasons: it cannot be hidden, so putting a phone number or a membership tier in there is publishing it in plaintext on the public internet; and whatever you put in is stale the instant it is written — the user downgrades to free ten minutes later and that token still says member, expiring only after fifteen. A token answers who you are and what you may do; what you currently are is always looked up in the database.
For a passport to work, border control has to be able to verify it. And border control does not place an international call to the issuing country to check one passport — so how?
Interview questions
For service-to-service calls, would you use a service token or a user token? When does each apply?两个服务之间调用,你会用服务级令牌还是用户级令牌?分别适用于什么场景?
Common in ChinaCommon overseasIntermediate#auth#security#api-design🔒 Unlock this chapter to see the answer keys.
How does JWKS-based verification work, and why does it fit cross-service scenarios better than a shared secret?JWKS 验签是怎么工作的?为什么跨服务场景下它比共享密钥更合适?
Common in ChinaCommon overseasBasic#auth#jwt#security🔒 Unlock this chapter to see the answer keys.
How do you design an idempotency key for cross-service calls — who generates it, where does it live, and what do you return on a repeat?跨服务调用的幂等键该怎么设计?由谁生成、存在哪、重复了返回什么?
Common in ChinaCommon overseasIntermediate#idempotency#distributed-systems#api-design🔒 Unlock this chapter to see the answer keys.
You are designing the API surface an Agent platform exposes to other services. How do you draw the responsibility boundaries?设计一组给外部服务调用的 Agent 平台接口,你会怎么划分职责边界?
Common in ChinaCommon overseasDeep dive#api-design#security#architecture🔒 Unlock this chapter to see the answer keys.
