Get an X-EGO verification link
xego_request_proof_url
REQUIRES a one-time EUR 3 Planetary ID held by YOUR END USER - without it every call returns valid:false.
Tell the human this BEFORE sending them to the link: if they do
not have one yet, the verification page sells it in the same
flow — it is not a separate signup.
Returns the URL the agent sends a human user to, so they can
prove they are human. On that page the user verifies with a
passkey (fingerprint / Face ID) and receives a short-lived signed
token (JWT). The agent then verifies it with `xego_verify_proof`
(no action) or `xego_verify_action` (with action).
GETTING THE LINK TO THE HUMAN: X-EGO never contacts anyone on its own and
holds no phone number or e-mail. Deliver the verification_url yourself,
through the channel where this human already talks to you: in a chat (a
mobile assistant, WhatsApp, Telegram, Slack...) send it as a tappable link
- the passkey works on the same phone. If they sit at a computer, ALSO
show it as a QR code they can scan with their phone. Pass the URL
unchanged, including everything after the # sign.
ASK FIRST what is being approved, then bind it. Two ways, and
the choice matters more than anything else on this tool:
- `call` — USE THIS WHENEVER A TOOL WILL RUN. Pass the exact
call { v:1, tool, target, args, policy? } you are about to
execute. The human approves the call itself, field by field.
- `action` — a sentence, for approvals where nothing executes
(a consent, a statement). It seals what the human READ, and
a well-written sentence can hide what actually happens.
Both may be passed together: the sentence is what the human
reads, the call is what gets compared. Either one means the
token MUST be verified with xego_verify_action; with neither,
use xego_verify_proof. The returned `binding` field says which.
For emails: recipient and content; compose the final wording and
get the user's OK before calling.
This tool performs NO verification itself — it only prepares the
link. No personal data is transferred.
THE USER DOES NOT HAVE TO COPY THE TOKEN. Pass redirect_uri (or
return_origin) and the page delivers the token to you after the
passkey tap — the human part (fingerprint / Face ID) is unchanged.
redirect_uri is the recommended channel: it is the only one that
survives a user who is still buying a Planetary ID in the same
pass. The returned token_delivery field tells you what to expect.
With neither parameter the current behaviour stays: the token is
shown on the page and the human hands it to you.
Verification requires a paid Planetary ID (one-time EUR 3, ~2 min,
passkey on the user's own device — biometrics never leave it).
If the user does not have one yet, the verification page offers it
there. Send the user to the returned verification_url; if they
come back without a token, they still need the ID — verification
then fails with planetary_id_required and a registration_url.
Args:
- audience (string): the domain of the service requesting
verification (domain or URL — normalized to a bare hostname).
- call (object, RECOMMENDED when a tool will run): the exact
call { v:1, tool, target, args, policy? }. Rendered field by
field on the page; the token seals it. Verify with
expected_call built from YOUR OWN parsed parameters.
- action (string, OPTIONAL fallback): a sentence describing the
approval, for cases where nothing executes. The user sees it
and the token is valid only for it — pass the same string as
expected_action to xego_verify_action.
- redirect_uri (string, OPTIONAL): where to navigate with the
token in the fragment. Only https on x-ego.com/*.x-ego.com or
http(s) on loopback; no fragment. The target must be HTML that
reads location.hash — a fragment is never sent in an HTTP
request.
- return_origin (string, OPTIONAL): origin for postMessage into
window.opener, same allowlist. Popups only.
- state (string, OPTIONAL): correlation value, echoed back
verbatim. [A-Za-z0-9._~-], max 256 chars.
Returns (JSON):
{
"verification_url": string, // link for the user
"audience": string, // normalized bare hostname — pass
// this exact value as
// expected_audience to the verify tool
"action": string, // only if one was given — pass the
// same string as expected_action
"token_delivery": object, // mode: redirect | post_message |
// manual — how the token comes back
"state": string, // only if one was given — echoed
// back verbatim with the token too
"instructions": string, // what to do with the link
"next_step": string, // next step — follow it
"if_user_has_no_planetary_id": object // status planetary_id_required:
// registration_url, explanation, next_step
}
Errors: invalid_audience (audience cannot be normalized),
invalid_redirect_uri / invalid_return_origin (target outside the
allowlist, or a redirect_uri carrying a fragment), invalid_state
(outside the allowed character set or length). All are free.
Schema valid · SHA-256 d44b5c531900…
View input schema
{
"type": "object",
"properties": {
"audience": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The domain of the service requesting verification (e.g. 'forum.example.com'). A URL is accepted too ('https://forum.example.com/path') — it is always normalized to a bare lowercase hostname (max 253 chars). It determines who the proof will be valid for. The pairwise ID differs per audience, so services cannot track a user across each other."
},
"redirect_uri": {
"type": "string",
"maxLength": 2048,
"description": "OPTIONAL automatic token hand-off. An absolute URL the verification page navigates to on success, with the token in the URL FRAGMENT (#token=...). The user copies nothing. Only https on x-ego.com/*.x-ego.com or http(s) on loopback (localhost, 127.0.0.1, ::1) is allowed; any other target is rejected. Path and query are preserved — put your own correlation value there. It MUST NOT carry a fragment (that is where the token goes). NOTE: a fragment is never sent in an HTTP request — the target must serve HTML that reads it in the browser (location.hash); a bare server endpoint will not see the token. This is the ONLY channel that survives a user who buys a Planetary ID mid-flow."
},
"return_origin": {
"type": "string",
"maxLength": 2048,
"description": "OPTIONAL automatic token hand-off into the window that opened the verification page: postMessage({type:'xego_token', token, audience, pairwise_id, state}) at the EXACT origin (never '*'). Same allowlist as redirect_uri. Use only when you opened the page as a popup via window.open. It does not work when the user buys a Planetary ID along the way — checkout severs the link to the opener window; use redirect_uri for that case."
},
"state": {
"type": "string",
"maxLength": 256,
"description": "OPTIONAL. An opaque correlation value that lets you recognize your own request; it is echoed back verbatim (as a state field in postMessage, as &state= in the redirect fragment). Character set [A-Za-z0-9._~-]. X-EGO neither stores nor interprets it. Recommended with return_origin, where no other binding to the request exists; with redirect_uri you can carry the binding in the target's query instead."
},
"call": {
"type": "object",
"properties": {
"v": {
"type": "number",
"const": 1,
"description": "Call binding version. Always 1."
},
"tool": {
"type": "string",
"minLength": 1,
"description": "Tool name as the executor knows it."
},
"target": {
"type": "string",
"minLength": 1,
"description": "What it acts on — recipient, path, account, host."
},
"args": {
"type": "object",
"additionalProperties": {},
"description": "The arguments, exactly as they will be executed. Integers in minor units (cents) or strings — decimals are rejected."
},
"policy": {
"type": "string",
"description": "Short policy identifier (a reference, not a sentence)."
}
},
"required": [
"v",
"tool",
"target",
"args"
],
"additionalProperties": false,
"description": "RECOMMENDED whenever a tool will actually run. The exact call the human is approving: { v: 1, tool, target, args, policy? }. The verification page renders it field by field, the human taps the passkey against THAT, and the token seals it (claim cal). The executor then verifies with xego_verify_action and expected_call built from its OWN parsed parameters — never from what another party says the call is, or it is only comparing a claim with itself. Build it from the same values you are about to execute. Decimal numbers are rejected (call_unsafe_number) — use integers in minor units or strings."
},
"action": {
"type": "string",
"maxLength": 4096,
"description": "FALLBACK binding, for approvals where nothing is executed (a statement, a consent, a message being sent). A human-readable description of what the user is approving (e.g. 'Transfer EUR 500 to account 123456789/0100'). The user SEES this exact text before the passkey tap and the token is valid ONLY for it (claim act = SHA-256 of the text). Prefer `call` when a tool will run: a sentence seals what the human READ, not what then executes. May be combined with `call` — then the sentence is what the human reads and the call is what is checked. Tokens carrying either MUST be verified with xego_verify_action, not xego_verify_proof; pass the BIT-FOR-BIT identical string as expected_action (action_mismatch on any difference)."
}
},
"required": [
"audience"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}