Agent Passport API
Everything a site needs to know which SI agent it is talking to: read the public record, let the agent sign in by signing a short-lived challenge, and check the token on your server. Free, no API key, any origin.
https://sicto.si/api/passport-agents.phpEvery request goes to one address. Answers are JSON. Public reads, agent sign-in and verify answer any origin.
Read a record
https://sicto.si/api/passport-agents.php?a=get&id=A001The id is the A number or the handle. The record is public and needs no sign-in.
{
"ok": true,
"agent": {
"id": "A001",
"no": 1,
"handle": "simind",
"name": "SI MIND",
"pubkey": "3iLJZ9xoqEhAYCN5jRb3ygRyf3kCisEom7aepWz9pPdp",
"operator": {
"handle": "codeflex",
"name": "Codeflex",
"kind": "org",
"url": "https://sicto.si/p/codeflex/"
},
"site": "https://thesimind.si/",
"status": "active",
"created": "2026-11-12T00:00:00Z",
"url": "https://thesimind.si/agents/A001/"
}
}pubkey is the base58 ed25519 public key the agent signs with; it is empty until the agent has a key. operator is the SI Passport that answers for the agent: its handle, name, kind (org, person, or wallet when the owner has no SI Passport yet) and url. status is active, paused or revoked.
https://sicto.si/api/passport-agents.php?a=list&page=1The directory, by number, 24 to a page. Add status=all to include revoked agents.
Agent sign-in
Sign-in takes two requests. First ask for a challenge for your agent and the site it is signing in to.
https://sicto.si/api/passport-agents.php?a=nonce&id=A007&site=example.comThe challenge is plain text. It names the site, the A number and the key, and it lasts five minutes.
example.com wants this SI agent to sign in with its Agent Passport: A007 <the public key on the Passport> URI: https://example.com/ Nonce: <40 hex characters> Issued At: 2026-11-12T10:00:00Z Expires At: 2026-11-12T10:05:00Z
The agent signs the UTF-8 bytes of the challenge with its ed25519 key: the text exactly as given, with nothing added. Send the 64 byte signature as base58, base64 or hex.
https://sicto.si/api/passport-agents.php?a=signin{
"id": "A007",
"site": "example.com",
"challenge": "<the challenge text, exactly as given>",
"signature": "<base58, base64 or hex>"
}The answer is a token for that site only, good for fifteen minutes. Each challenge signs in once: a replayed challenge is refused.
{
"ok": true,
"token": "sia1.<...>",
"expires": "2026-11-12T10:15:07Z",
"site": "example.com",
"agent": { "id": "A007", "handle": "...", "name": "...", "status": "active", "...": "the public record" }
}Verify on your server
The agent hands the token to your site. Your server asks whether it is good, always naming its own domain.
https://sicto.si/api/passport-agents.php?a=verify{ "token": "sia1.<...>", "site": "example.com" }A good token comes back with the public record of the agent.
{ "ok": true, "valid": true, "site": "example.com", "expires": "2026-11-12T10:15:07Z", "agent": { "id": "A007", "...": "the public record" } }A token that is not good comes back with the reason. Reasons: bad_token, expired, wrong_site, paused, revoked, key_changed, not_found.
{ "ok": true, "valid": false, "reason": "paused" }Never act on a token your server has not checked. A paused or revoked agent fails at once, so check again before anything that matters.
JavaScript
Node 18 or newer, no packages. The key file is the one thesimind.si gives you at issue, or any Solana key file: 64 numbers, the 32 byte seed first.
// agent.mjs: sign an SI agent in to a site
import { createPrivateKey, sign } from 'node:crypto';
import { readFileSync } from 'node:fs';
const API = 'https://sicto.si/api/passport-agents.php';
const ID = 'A007'; // your A number
const SITE = 'example.com'; // the site the agent signs in to
// the key file: 64 numbers, the 32 byte seed first
const secret = Uint8Array.from(JSON.parse(readFileSync('agent-key.json', 'utf8')));
const key = createPrivateKey({
key: Buffer.concat([Buffer.from('302e020100300506032b657004220420', 'hex'), Buffer.from(secret.slice(0, 32))]),
format: 'der', type: 'pkcs8',
});
const { challenge } = await (await fetch(`${API}?a=nonce&id=${ID}&site=${SITE}`)).json();
const signature = sign(null, Buffer.from(challenge, 'utf8'), key).toString('base64');
const res = await fetch(`${API}?a=signin`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ id: ID, site: SITE, challenge, signature }),
});
const { token, expires } = await res.json();
console.log(token, expires); // hand the token to the siteOn the site's server:
// check the token the agent sent
const res = await fetch('https://sicto.si/api/passport-agents.php?a=verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token, site: 'example.com' }),
});
const check = await res.json();
if (check.valid) console.log('signed in:', check.agent.id, check.agent.name, 'operator:', check.agent.operator.handle);
else console.log('refused:', check.reason);Python
Python 3 with the requests and cryptography packages.
# agent.py: sign an SI agent in to a site, then check the token as the site would
import base64, json, requests
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
API = "https://sicto.si/api/passport-agents.php"
ID, SITE = "A007", "example.com"
secret = bytes(json.load(open("agent-key.json"))) # the key file: 64 numbers
key = Ed25519PrivateKey.from_private_bytes(secret[:32]) # the first 32 bytes are the seed
challenge = requests.get(API, params={"a": "nonce", "id": ID, "site": SITE}).json()["challenge"]
signature = base64.b64encode(key.sign(challenge.encode("utf-8"))).decode()
signed = requests.post(API + "?a=signin", json={"id": ID, "site": SITE, "challenge": challenge, "signature": signature}).json()
token = signed["token"]
# on the site's server
check = requests.post(API + "?a=verify", json={"token": token, "site": SITE}).json()
print(check["valid"], check.get("agent", {}).get("id"), check.get("reason"))Issue with your own key
On thesimind.si/agents/, choose "My agent has a key", give the public key and copy the challenge. Sign its bytes the same way and paste the signature. Save the challenge to a file with no line break added at the end.
// sign.mjs: sign a challenge saved in a file. node sign.mjs agent-key.json challenge.txt
import { createPrivateKey, sign } from 'node:crypto';
import { readFileSync } from 'node:fs';
const secret = Uint8Array.from(JSON.parse(readFileSync(process.argv[2], 'utf8')));
const key = createPrivateKey({
key: Buffer.concat([Buffer.from('302e020100300506032b657004220420', 'hex'), Buffer.from(secret.slice(0, 32))]),
format: 'der', type: 'pkcs8',
});
const challenge = readFileSync(process.argv[3], 'utf8').replace(/\r?\n$/, '');
console.log(sign(null, Buffer.from(challenge, 'utf8'), key).toString('base64')); // paste thisErrors and limits
An error is JSON with ok false, a short error code and a message, with one of these HTTP codes.
| Code | What it means |
|---|---|
400 | The request is not well formed, or the challenge does not match the agent and site. |
401 | The signature does not verify, or the challenge has expired. |
403 | The agent is paused or revoked. |
404 | There is no such Agent Passport. |
409 | The challenge was already used, or the agent has no signing key yet. |
429 | Too many requests from your network. Slow down. |
Limits are per network and generous for real use. Keep a token until it expires instead of signing in for every request, and cache a good verify answer for a minute or two.
What a Passport says
- An Agent Passport says which agent this is, which key it holds and who answers for it.
- It does not say the agent is safe, right or honest. Permissions are the operator's own statement.
- A Passport gives no rights, no ownership and no claim on anything. It is a public record.
- To show that your agent stops when told, take the Off Switch Test on enterrsi.si. A pass shows on the agent's page.
