Agent Identity & MCP
How an org’s own automation (a cron job, a CI pipeline, an internal bot) gets its own identity in the platform, so audit events and usage attribute to that automation specifically — not just to the API key it happens to run under.
Three parts are built, and this guide covers only those:
- Identity (Slice A): an agent gets its own credential, and the platform records what it does under its own name.
- Presenting identity (Slice B v1): the agent proves who it is to an external relying party.
- Skills (Slice C): an administrator grants an agent a skill against a
named application, for example creating payment orders in it within
stated limits. The agent presents identity and skill to that application’s
verifier, either through the MCP tool
present_to_requestor, from a backend, throughPOST /api/agents/{agentId}/presentwith a narrowagent-presentAPI key.
The rationale and scoping decisions are in
AGENT_IDENTITY_MCP_PLAN.md,
AGENT_IDENTITY_MCP_SLICE_B_PLAN.md
and
AGENT_IDENTITY_MCP_SLICE_C_PLAN.md
(original note:
AGENT_IDENTITY_MCP.md). Not
built: one agent verifying or vouching for another, keys held by the agent’s
own runtime, and verifiers on other platforms. Read Status and
limitations at the bottom before you rely on any of this in a deployed
environment.
The pieces, in one picture
Section titled “The pieces, in one picture”
sequenceDiagram
participant Admin as Org admin (API key, admin scope)
participant P as Platform
participant Sign as Signing service
participant Aud as Audit log
note over Admin,P: one-time per deployment — an AgentIdentityCredential<br/>template must exist (dc+sd-jwt format)
Admin->>P: create_agent_identity(name, templateId)
P->>Sign: createKey (ES256)
Sign-->>P: keyRef, publicKeyJwk
P->>P: issue AgentIdentityCredential (SD-JWT VC)
P-->>Admin: agentId
Admin->>P: open_agent_session(agentId)
P->>Sign: sign KB-JWT (platform acts as the agent's own wallet)
P->>P: verify its own presentation (signature + nonce/aud/vct binding)
P-->>Admin: sessionToken (Redis, 30 min TTL, scopes ≤ API key's own)
Admin->>P: issue_credential / verify_credential(sessionToken, ...)
P->>Aud: record actorType: "agent", actorId: agentId
P-->>Admin: result
The platform plays two roles here it doesn’t play anywhere else in the
system: issuer of the AgentIdentityCredential (ordinary — every
template-based issuance does this) and wallet/holder of that same
credential (new — something has to hold the cnf-bound private key and
produce a key-binding JWT at presentation time; the platform does this
itself, on the agent’s behalf). For internal attribution (Slice A), the
platform is also the only relying party, verifying its own issued credential
to prove the caller controls the agent’s key before minting a session — a
possession check, not a trust decision between independent parties.
Slice B v1 extends this to a real external relying party: the platform
mints a presentation bound to that party’s own audience/nonce and does not
verify it itself — the external party does, independently, the same way it
would verify any dc+sd-jwt credential from this platform. See
Presenting to an external relying party, below.
Skills (Slice C) add a second credential, granted by a person, and a presentation that answers a request a verifier created on this platform, so the platform’s own verifier checks it. See Skills, below. One agent verifying or vouching for another is not built.
| Role | What it identifies | Credential / secret | Where it’s checked |
|---|---|---|---|
| Human console user | a person | OIDC access token (Zitadel) | AuthGuard + RolesGuard, org role admin | developer | auditor | billing |
| API key | an org (machine-to-machine) | opaque secret vcp_... |
ApiKeyGuard, scoped issue | verify | admin, or agent-present alone (presents for named agents to named verifier orgs, nothing else) |
| Agent identity | one named automation, scoped under an API key | a platform-issued AgentIdentityCredential (SD-JWT VC) |
for internal use, checked once at open_agent_session (proof of possession); for external use, presented via present_agent_identity and checked by whoever receives it |
| External relying party | a real third-party application/organization the agent presents its identity to | — | checks independently: the x5c chain in the credential header (issuer signature, validated to the deployment’s issuer trust anchor), cnf.jwk (holder binding), the public token-status-list URL (revocation) — nothing platform-specific |
| Verifier application | an application (an org on this platform) that lets the agent act within a skill, e.g. capture payment orders | its own API key (verify scope) to create the request |
the platform checks issuer key, status, nonce and audience; the application checks the same holder key on both credentials, its own application id, and enforces constraints |
| (not built) Relying-party agent | a different agent verifying or vouching for this one | — | not scoped |
An agent identity is not a new authorization tier. It never carries more scope than the API key that created it — opening a session or presenting to an external party is attribution/proof, not a way to escalate what a caller can do.
Where credentials are stored
Section titled “Where credentials are stored”| What | Where | Form |
|---|---|---|
| Agent’s private key | Signing service | Never leaves it. The agent_identities table only holds an opaque keyRef pointing at it — same pattern org_signing_keys uses for issuer keys. |
| Agent’s public key | agent_identities.public_key_jwk (Postgres) |
Public JWK, in the clear — it’s public by definition. |
AgentIdentityCredential (the rendered wire credential) |
issued_credentials table |
An ordinary row, same as any other issued credential. agent_identities.credential_id points at it. |
| API key secret | api_keys.key_hash |
SHA-256 hash only; only an 8-char prefix is ever stored in the clear. The raw secret is shown once at creation and never again. |
| Agent session token | Redis, key agent-identity:session:<orgId>:<token> |
30-minute TTL, SET ... EX. Holds {agentId, orgId, apiKeyId, scopes}. |
agent_identities is org-scoped with Postgres row-level security
(org_isolation policy, FORCE ROW LEVEL SECURITY) — the same isolation
model every other tenant-scoped table gets.
How identity is verified
Section titled “How identity is verified”Two independent layers, checked at different times:
- Every HTTP request to
POST /api/mcpgoes through the sameApiKeyGuardas every other API-key-authenticated route: the bearer secret is SHA-256 hashed and resolved via theresolve_api_key()Postgres function, which also checksrevoked_at/expires_at. There is no separate transport-level credential for agents — the MCP endpoint is an ordinary API-key-guarded route. - Opening an agent session (
open_agent_session) is where the agent’s own credential actually gets used: the platform builds a KB-JWT-bound SD-JWT presentation (signed by the signing service using the agent’skeyRef), then verifies that presentation itself — signature, disclosures, and nonce/audience/vctbinding — before minting the session token. This proves whoever is calling the MCP tools genuinely controls the agent’s key; it is not re-checked on every subsequent call, only the (cheaper) Redis session lookup is.
Presenting to an external party (present_agent_identity) uses the same
KB-JWT-signing step but for a caller-supplied audience/nonce, and
deliberately skips the self-verify step — the external relying party
verifies it independently, the same way it would verify any dc+sd-jwt
credential from this platform (the x5c chain, cnf.jwk, the public status-list
URL). See Presenting to an external relying party, below.
Revocation: revoke_agent_identity sets agent_identities.revoked_at
and revokes the credential’s real status-list entry (the same mechanism
POST /credentials/{id}/revoke uses), so open_agent_session and any
external verifier checking the status list independently agree. Both
open_agent_session and present_agent_identity check revoked_at before
doing anything else.
User guide
Section titled “User guide”Setup (one-time per org)
Section titled “Setup (one-time per org)”-
Create a credential template for
AgentIdentityCredential, via the ordinary template endpoint — admin-console-only, an API key can’t do it (same restriction asCREDENTIAL_LOGIN_GUIDE.md’s template-creation step:POST /api/orgs/{orgId}/templatesis guarded by a user session, notApiKeyGuard) — withdc+sd-jwtin itsformats(the only format an agent session can present) andrevocable: true— required:create_agent_identityrejects a non-revocable template, since an identity that can be handed to an external party must also be killable from that party’s point of view:POST /api/orgs/{orgId}/templatesAuthorization: Bearer <access token>{ "name": "AgentIdentityCredential", "claimsSchema": { "type": "object" }, "formats": ["dc+sd-jwt"], "revocable": true } -
Create (or reuse) an API key with the
adminscope in that org —create_agent_identityandopen_agent_sessionboth require it:POST /api/orgs/{orgId}/api-keysAuthorization: Bearer <access token>{ "name": "agent-ops-key", "scopes": ["issue", "verify", "admin"] } -
Point an MCP client at the platform. The endpoint is
POST /api/mcp, Streamable HTTP, stateless (a fresh server per request — there’s no MCP-level session to resume, only the agent session described below). Authenticate with the API key from step 2:Authorization: Bearer <api key secret>A generic MCP client config looks like:
{"mcpServers": {"vc-platform": {"type": "http","url": "https://<your-platform-host>/api/mcp","headers": { "Authorization": "Bearer <api key secret>" }}}}"type": "http"matters: Claude Code treats aurlentry without a type as a stdio server and fails to connect. Client-specific setup, including Claude Code and Claude Desktop, is in Connecting Claude below.
Connecting Claude (Code and Desktop)
Section titled “Connecting Claude (Code and Desktop)”Prerequisites: Setup steps 1–2 above — an AgentIdentityCredential
template (revocable: true, created through the console) and an API key
with issue, verify and admin scopes. The key secret is shown once, at
creation. The MCP endpoint is https://<your-platform-host>/api/mcp (note
the /api prefix: /mcp alone is a 404). Sandbox host: dev.api.sideos.eu.
Claude Code
Section titled “Claude Code”Status: verified — Claude Code 2.1.319 drove the six tools of that date
end to end against the sandbox on 2026-11-06. The seventh,
present_to_request, was added later and is covered by the in-repo MCP
client, not yet by a Claude Code run.
-
Keep the key in an environment variable, not in a file you might commit:
Terminal window export VCP_MCP_KEY='<api key secret>' -
Register the server. Two options; pick by who needs it.
Shared with a team — project scope. Commit a
.mcp.jsonat the project root that references the variable; every teammate exports their own key.${VAR}expansion is supported inurlandheaders:{"mcpServers": {"vc-platform": {"type": "http","url": "https://dev.api.sideos.eu/api/mcp","headers": { "Authorization": "Bearer ${VCP_MCP_KEY}" }}}}If
VCP_MCP_KEYis unset the config still loads (with a warning) and the literal text${VCP_MCP_KEY}is sent as the key, which the platform rejects with a 401. Claude Code asks each user to approve a project-scope server the first time.Just you — local scope (the default).
Terminal window claude mcp add --transport http vc-platform https://dev.api.sideos.eu/api/mcp \--header "Authorization: Bearer $VCP_MCP_KEY"Here your shell expands the variable at add time, so the secret is written to
~/.claude.jsonin plain text. Use--scope userto make it available in every project.claude mcp adddoes not validate the key; a wrong one only shows up when connecting. -
Check it connected.
claude mcp listshould showvc-platformas✔ Connected; inside a session,/mcpshows the server and its tool count (seven). The tools appear to Claude asmcp__vc-platform__create_agent_identity,…__open_agent_session,…__present_agent_identity,…__present_to_request,…__revoke_agent_identity,…__issue_credentialand…__verify_credential. Remove the server withclaude mcp remove vc-platform. -
Ask Claude to use it. For example:
Using the vc-platform tools: create an agent identity named
nightly-reconciliation-jobfrom template<AgentIdentityCredential template id>, open a session for it, issue a credential from template<other template id>with claims{"reconciled": true}, then verify that credential through the same session.Claude has to carry two values between calls: the
agentIdfromcreate_agent_identity, and thesessionTokenfromopen_agent_session(passed back asagentSessionToken). A session lasts 30 minutes; after thatissue_credential/verify_credentialanswer “agent session not found or expired” and Claude must open a new one. -
Permissions. Claude Code asks before each MCP tool call. Every tool here changes state, and
create_agent_identity/revoke_agent_identityin particular are worth keeping on a prompt. To pre-approve specific tools, add them topermissions.allowin your Claude Code settings, e.g.mcp__vc-platform__open_agent_session.
Unattended / CI use (headless):
claude -p "<prompt>" \ --mcp-config mcp.json --strict-mcp-config \ --tools "" \ --allowedTools "mcp__vc-platform__create_agent_identity,mcp__vc-platform__open_agent_session,mcp__vc-platform__issue_credential,mcp__vc-platform__verify_credential" \ --max-turns 25 < /dev/null--strict-mcp-config uses only that file’s servers, --tools "" removes
Claude’s built-in tools so it can act only through the MCP tools, and a tool
missing from --allowedTools is denied outright with no prompt (the call
never runs). Build that list carefully: a typo yields a run that does
nothing. Pass the key through the environment (${VCP_MCP_KEY} in
mcp.json), never inline.
Claude Desktop
Section titled “Claude Desktop”Status: not verified by us, and the instructions below are community-sourced, not from Anthropic’s documentation. Confidence: low.
This platform authenticates with a static API key in an Authorization
header and does not implement MCP’s OAuth flow. Claude Desktop’s
claude_desktop_config.json (macOS:
~/Library/Application Support/Claude/claude_desktop_config.json) launches
local stdio servers, so a remote server with a static header is normally
reached through a bridge such as the community
mcp-remote package:
{ "mcpServers": { "vc-platform": { "command": "npx", "args": ["-y", "mcp-remote", "https://dev.api.sideos.eu/api/mcp", "--header", "Authorization:${VCP_AUTH}"], "env": { "VCP_AUTH": "Bearer <api key secret>" } } }}(The header value lives in env rather than args because of a reported
Windows quirk with spaces in args.) Restart Claude Desktop after editing.
This puts the key in a plain-text file on the machine. Whether current
Claude Desktop builds offer a native remote-server option that accepts a
custom header was not established — check Anthropic’s current MCP
documentation, and once you have it working, record the result here and in
requirements/AGENT_IDENTITY_MCP_PLAN.md (Claude Desktop is the one client
still open on the gate).
Security notes
Section titled “Security notes”- The API key is an org-wide admin credential (
adminscope is whatcreate_agent_identity,open_agent_session,present_agent_identityandrevoke_agent_identityrequire). Anyone, or any Claude session, holding it can create and revoke agent identities and issue credentials for the org. Use one dedicated key per client or person so it can be revoked on its own (DELETE /api/orgs/{orgId}/api-keys/{keyId}, console login required); a revoked key is rejected with a 401 immediately. - If a backend only needs to present an agent’s skill to a verifier, give it
an
agent-presentkey instead of an admin key (see Presenting from a backend). It cannot create, revoke or issue anything. - An agent session never carries more than the key’s own scopes. It is attribution, not extra privilege.
- Don’t attach this server to a Claude session that also reads untrusted
content (web pages, inbound email, other MCP servers’ output): injected
instructions could make Claude issue or revoke credentials with this key.
For unattended runs, restrict
--allowedToolsto what the job needs. sessionTokenand thepresentationreturned bypresent_agent_identityare bearer values: don’t paste them into logs or tickets. A presentation is bound to theaudienceandnonceyou supplied.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause |
|---|---|
✘ Failed to connect / 401 |
Key wrong, revoked, or VCP_MCP_KEY unset (the literal ${VCP_MCP_KEY} was sent). |
| Connects as stdio and fails | url entry without "type": "http". |
404 on /mcp |
The path is /api/mcp. |
| “this API key does not carry the admin scope” | Key was created without admin. |
| “agent session not found or expired” | Sessions last 30 minutes; call open_agent_session again. |
| “agent identity has been revoked” | Expected after revoke_agent_identity; create a new identity. |
create_agent_identity rejects the template |
The template is not revocable: true. |
unexpected "aud" claim value (401) |
You used a console/service-account token on an API route that wants an API key, or the token lacks the project audience; unrelated to the MCP key. |
Issue (create an agent identity)
Section titled “Issue (create an agent identity)”Call the create_agent_identity tool:
tool: create_agent_identityarguments: { "name": "nightly-reconciliation-job", "templateId": "<template id from setup>" }→ { "agentId": "<uuid>", "name": "nightly-reconciliation-job" }This mints an ES256 keypair in the signing service and issues the
AgentIdentityCredential through the ordinary issuance pipeline. No raw key
material is ever returned — only agentId.
Verify (open a session, then act as the agent)
Section titled “Verify (open a session, then act as the agent)”“Verify” here means proving the caller controls the agent’s key, which happens once, at session-open:
tool: open_agent_sessionarguments: { "agentId": "<uuid from create_agent_identity>" }→ { "sessionToken": "<uuid>", "agentId": "<uuid>", "expiresAt": "<ISO timestamp>" }Internally: the platform presents the AgentIdentityCredential to itself
(KB-JWT signed via the signing service) and verifies that presentation
before minting sessionToken. If agent_identities.revoked_at is set, this
call is refused.
From here, ordinary issuance/verification calls carry the agent’s attribution instead of just the API key’s:
tool: issue_credentialarguments: { "agentSessionToken": "<sessionToken>", "templateId": "<some other template>", "subjectClaims": { "reconciled": true }, "format": "vc+jwt"}
tool: verify_credentialarguments: { "agentSessionToken": "<sessionToken>", "credential": "<raw credential string>" }Each requires the session to carry the matching issue/verify scope
(inherited from the API key that opened it, never more).
Confirm attribution by querying the audit log — this is the actual point of the feature:
GET /api/orgs/{orgId}/audit-events?action=credential.verifiedAuthorization: Bearer <access token>Look for an event with actorType: "agent" and actorId equal to the
agentId, rather than actorType: "api_key".
Presenting to an external relying party
Section titled “Presenting to an external relying party”This is Slice B v1: proving the agent’s identity to a real third-party
application, not just attributing internal audit events. Call
present_agent_identity with whatever audience/nonce that external
party’s own protocol has handed you (out of band — this platform doesn’t
speak that protocol, it only mints the proof):
tool: present_agent_identityarguments: { "agentId": "<uuid from create_agent_identity>", "audience": "https://relying-party.example/verify", "nonce": "<value the relying party asked you to bind to>"}→ { "presentation": "<compact SD-JWT VC>~<disclosures>~<KB-JWT>" }The platform does not verify this presentation itself — hand it to the
relying party, and they check it exactly the way they’d check any other
dc+sd-jwt credential from this platform. There is one coordination step:
the relying party needs this deployment’s issuer trust anchor.
- Issuer signature — the credential has no
iss. The issuer is the leaf certificate of thex5cheader (ES256; subjectCN=org-<orgId> SD-JWT VC Issuer), which must chain to the deployment’s issuer trust anchor (HAIP 1.0 §6.1.1 —did:jwkis not used fordc+sd-jwt). The anchors are published in the repository underdocs/trust/(sandbox and production issuer roots, IACA). The two roots share a subject name, so pin the SPKI SHA-256 listed there, not the subject. Every org on a deployment chains to the same root, so chain validation alone shows “an org on this platform”; also check that the org id in the leaf subject is the org you expect. - Holder binding (proof of possession) — the KB-JWT’s signature is
checked against the
cnf.jwkclaim embedded in the credential itself. Also self-contained. - Nonce/audience — the relying party checks the KB-JWT’s
nonce/audmatch what it asked for (replay protection is on them, same as any OpenID4VP verifier). - Revocation — fetch
GET /token-status-lists/{orgId}/{listId}(the URI is embedded in the credential’sstatusclaim), public and unauthenticated by design.
If your own org wants to sanity-check a presentation the same way an
external party would, POST /api/credentials/verify runs the same generic
checks (1, 2, and 4 — it has no concept of expected nonce/audience, since it
doesn’t know who’s asking).
Skills: granting an agent authority, and presenting it to a verifier
Section titled “Skills: granting an agent authority, and presenting it to a verifier”An identity says who the agent is. A skill says what an application may
let it do. The first skill type is payment-order-create: the
agent may create payment orders in a named application, up to a stated
amount per order, from stated debtor accounts. It is a
skill against that application only, not a mandate to execute or authorise a
payment. Its canonical type is
<platform>/vct/v1/skills/payment-order-create/{version}, the same for every
organisation on a deployment. Two versions exist:
- Version 1: payees are a stated list, at least one.
- Version 2 (platform 3.33.0, what the console grants): a payee policy,
chosen with no default.
listedworks as version 1.anyhas no payee list, so the application may accept any creditor. It requires a largest total per day, between one and 100 times the largest order. Without a payee list, nothing stops a wrong IBAN (for example one taken from a manipulated invoice), so the console showsanyas a warning on the form and on the approval screen. The application must then keep its own controls: the amounts, the person confirming each order, and the release at the bank.
The second skill type is account-transactions-read (platform 3.34.0): the
agent may read the bookings of listed accounts in a named application. It
cannot create, change or cancel anything; an application that has both skills
logs an agent in with one of them per session. Its terms are the accounts (1
to 100), an optional earliest booking date (none: everything the
application holds) and whether incoming payments are included (no
default). Bookings name third parties (payees, payers, salaries and their
IBANs), so the console shows that as a warning on the approval screen. Which
person behind a shared agent may read which account is the application’s
decision, not a term of the skill.
Granting a skill is a person’s decision, made in the console. In the
organisation’s Agents tab an administrator chooses the skill and enters its terms (the
application and the verifier organisation; for payment orders the largest order, the payee policy,
the amount per day, the debtor accounts, and with listed the payees; for reading bookings the accounts,
the earliest date and whether incoming payments are included), reads them back exactly as the platform recorded them,
and approves by signing in again. That fresh sign-in is checked by the
platform (step-up authentication: auth_time, a nonce for this approval, and
the methods used are recorded), so an API key, the agent itself, or an old
session cannot grant one. Multi-factor authentication is always required: a
password alone is refused, so an administrator needs a second factor enrolled at
the identity provider to approve. Every other route to a skill (POST /credentials,
wallet offers, the MCP tools) answers 403. The grant records who approved it,
when and how they signed in, and a hash of the exact terms. A grant is
time-limited (by default one day for payment-order-create version 1, 30 days for version 2 and for account-transactions-read; at most 90) and can be revoked in the same tab at once.
The grant names the verifier organisation: the one organisation on this platform the agent may present the skill to. The administrator consents to that, and to no other: an agent’s limits are never shown to a verifier nobody named. Ask the application’s team for its organisation ID.
Presenting. The verifier (for example the application’s backend) creates a
presentation request with its own API key, asking for both credentials by type
and pinned to the agent’s organisation, then hands the agent the
authorizationRequest it gets back:
POST /api/presentations/requests (verifier's API key){ "credentials": [ { "id": "identity", "vct": "<identity type>", "issuer": { "orgId": "<agent's org>" }, "requestedClaims": ["name"] }, { "id": "skill", "vct": "<platform>/vct/v1/skills/payment-order-create/1", "issuer": { "orgId": "<agent's org>" }, "requestedClaims": ["skill", "application", "constraints"] } ], "signed": true }→ { "id": "<request id>", "authorizationRequest": "openid4vp://…" }tool: present_to_requestarguments: { "agentId": "<uuid>", "request": "<the authorizationRequest>" }→ { "requestId": "…", "verifierOrgId": "…", "accepted": true, "presented": [{ "queryId": "identity", "kind": "identity", … }, { "queryId": "skill", "kind": "skill", … }], "outcome": [{ "queryId": "identity", "verified": true, "errorCodes": [] }, … ] }What the tool guarantees, and what it refuses:
- It signs with the agent’s key for the audience and nonce of the request the verifier stored; the string you pass only points at it, so no one can have the agent sign for an audience of their choosing.
- Both credentials are signed by the same key, so a verifier that requires the same holder key on the identity and the skill gets it.
- A skill goes only to the organisation its grant names, and only while the grant is active (not revoked, not expired). The identity alone is presented only inside the agent’s own organisation; to anyone else it travels only with a skill that verifier was named for. Anything else is refused with the reason, and nothing is signed or sent.
- When the agent holds more than one active grant of the requested skill for the same verifier, the newest one is presented (the one approved last). To change an agent’s terms, approve the new grant first, then revoke the old one: revoking first leaves the agent without a grant in between.
- Only requests created on this platform are accepted, and none is fetched
from an address you supply. Requests that ask for an encrypted response
(
jarm) and Digital Credentials API requests are refused for now.
What the verifier checks (the platform’s own verifier does all of this when
the request is created with the verifier’s API key): both credentials were
issued by the pinned organisation, by its issuer key, not just by a subject
that looks right; each has a status reference and is not revoked; the nonce and
audience are the request’s. The verifier must itself check that the two results
carry the same holderKeyId, that application is its own identifier, and then
enforce the limits it reads in constraints: the platform does not enforce them
for it. Each result also carries validUntil (the credential’s own expiry), so
a verifier that opens a session on the strength of the presentation can cap the
session there. A revocation after that point does not end a session that is
already open; ending it is the verifier’s job.
Presenting from a backend: the agent-present key
Section titled “Presenting from a backend: the agent-present key”A verifier’s backend that is not an MCP client (for example a service that logs
an agent in to an application on its users’ behalf) can make the same
presentation over REST. It should not hold an organisation-wide admin key for
this; give it a key with the agent-present scope.
-
Create the key in the console (API keys → new key, scope Agent presenter) or with the API. The scope must be the key’s only scope, and both lists are required (1 to 20 entries each):
POST /api/orgs/{orgId}/api-keysAuthorization: Bearer <access token>{ "name": "login-service-presenter", "scopes": ["agent-present"],"agentIds": ["<agent uuid>"], "verifierOrgIds": ["<verifier org uuid>"] }agentIdsare live agents of your organisation.verifierOrgIdsare the organisations whose requests the key may answer. Without the second list a stolen key could present the agent’s identity to any verifier on the platform. -
Present. The verifier creates the request as in Skills above; the backend passes the
authorizationRequeston:POST /api/agents/{agentId}/presentAuthorization: Bearer <agent-present key>{ "request": "<the authorizationRequest>" }→ { "requestId": "…", "verifierOrgId": "…", "accepted": true,"presented": [ … ], "outcome": [ … ] }The result is the same as
present_to_request’s, and the same rules apply (the stored audience and nonce, the grant’s named verifier, only requests on this platform, nojarm, no Digital Credentials API, no same-deviceredirectUri). A refusal by the verifier is200withaccepted: false.
What the key cannot do: every MCP tool other than present_to_request, the
verifier routes and the console routes refuse it. An agent or verifier outside
its lists is a 403, the same for an agent id that exists and one that does
not, and is audited as agent.present_refused. An admin key may still present
for any agent of its organisation.
Revoke an agent identity
Section titled “Revoke an agent identity”tool: revoke_agent_identityarguments: { "agentId": "<uuid>" }→ { "agentId": "<uuid>", "revokedAt": "<ISO timestamp>" }This sets agent_identities.revoked_at (blocking future
open_agent_session/present_agent_identity calls) and revokes the
credential’s real status-list entry, so an external relying party checking
status independently — via step 4 above — sees the same answer.
Status and limitations
Section titled “Status and limitations”- Where it runs. Everything in this guide is deployed to the sandbox
(
dev.api.sideos.eu) and to production (api.sideos.eu, platform 3.32.2 since 2026-11-12, which includes skills and theagent-presentkey). The end-to-end scripts have been run against a local stack and the sandbox, not against production. On 2026-11-15 an agent of one organisation logged in on the sandbox to a real application (CasheN) whose verifier is a different organisation, once throughpresent_to_requestand once throughPOST /agents/{agentId}/presentwith anagent-presentkey; both presentations verified and both logins were granted. Any other deployment may run an older version; ask its operator before relying on a feature there. - Custodial keys only. The
key_custodycolumn exists for a future non-custodial mode (the agent’s own runtime holding its key and supplying its own KB-JWT), but only'platform'is implemented today. - A console tab for skills, not for the rest. Agents are created and revoked through MCP with an API key; the Agents tab lists them and is where an administrator grants and revokes skills. Granting a skill needs a person signing in again (verified against the sandbox’s Zitadel on 2026-11-09, with password and a second factor).
- Agent to application, on this platform only.
present_to_requestandPOST /agents/{agentId}/presentlet an agent answer a verifier’s request with its identity and a skill, for verifiers on the same platform. Other platforms’ verifiers, encrypted responses (jarm), the Digital Credentials API and the same-device flow are refused, and the full chain has not been tried against a verifier that is not this platform’s. - Two skill types.
payment-order-create, versions 1 and 2, andaccount-transactions-readversion 1. The skill’s meaning and limits are the application’s; the platform proves who granted what, and that it is current, and leaves enforcement to the application. - MCP-client coverage: exercised by a real
@modelcontextprotocol/sdkclient in-repo and, on 2026-11-06, by headless Claude Code 2.1.319 against the sandbox (the six tools of that date, agent-attributed audit events;present_to_requestwas added later and is covered by the in-repo client). Claude Desktop connecting directly to this platform’s MCP endpoint has not been tried; its setup above is unverified.
For the full request/response reference of the underlying issuance/
verification calls, see openapi.yaml’s MCP and
Credentials sections; to try the surrounding org/template/API-key setup
live, use the Bruno collection.