Agent Passport API
网站想知道正在和哪个 SI 智能体打交道,需要的一切都在这里:读取公开记录,让智能体对一段短时挑战签名来登录,再在你的服务器上核验令牌。免费,无需 API 密钥,任何来源均可调用。
https://sicto.si/api/passport-agents.php所有请求都发往同一个地址。返回的是 JSON。公开读取、智能体登录和核验对任何来源开放。
读取记录
https://sicto.si/api/passport-agents.php?a=get&id=A001id 是 A 编号或标识。记录是公开的,无需登录。
{
"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 是智能体用来签名的 ed25519 公钥(base58);智能体有密钥之前为空。operator 是为智能体负责的 SI Passport:handle、name、kind(org、person,或在所有者尚无 SI Passport 时为 wallet)和 url。status 为 active、paused 或 revoked。
https://sicto.si/api/passport-agents.php?a=list&page=1目录按编号排列,每页 24 条。加上 status=all 可包含已吊销的智能体。
智能体登录
登录需要两次请求。首先为你的智能体和它要登录的网站请求一段挑战。
https://sicto.si/api/passport-agents.php?a=nonce&id=A007&site=example.com挑战是纯文本。它写明网站、A 编号和密钥,五分钟内有效。
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
智能体用它的 ed25519 密钥对挑战的 UTF-8 字节签名:文本原样,不添加任何内容。把 64 字节的签名以 base58、base64 或 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>"
}返回的是只对该网站有效的令牌,有效期十五分钟。每段挑战只能登录一次:重复使用的挑战会被拒绝。
{
"ok": true,
"token": "sia1.<...>",
"expires": "2026-11-12T10:15:07Z",
"site": "example.com",
"agent": { "id": "A007", "handle": "...", "name": "...", "status": "active", "...": "the public record" }
}在你的服务器上核验
智能体把令牌交给你的网站。你的服务器询问它是否有效,并始终带上自己的域名。
https://sicto.si/api/passport-agents.php?a=verify{ "token": "sia1.<...>", "site": "example.com" }有效的令牌会连同智能体的公开记录一起返回。
{ "ok": true, "valid": true, "site": "example.com", "expires": "2026-11-12T10:15:07Z", "agent": { "id": "A007", "...": "the public record" } }无效的令牌会连同原因一起返回。 原因:bad_token、expired、wrong_site、paused、revoked、key_changed、not_found。
{ "ok": true, "valid": false, "reason": "paused" }绝不要依据你的服务器没有核验过的令牌行事。被暂停或吊销的智能体会立即失效,所以在重要操作之前请再核验一次。
JavaScript
Node 18 或更高版本,无需任何包。密钥文件就是 thesimind.si 在签发时给你的那个,或任何 Solana 密钥文件:64 个数字,前 32 字节是种子。
// 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 site在网站的服务器上:
// 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,需要 requests 和 cryptography 两个包。
# 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"))用你自己的密钥签发
在 thesimind.si/agents/ 选择“我的智能体已有密钥”,填入公钥并复制挑战。用同样的方式对它的字节签名,然后粘贴签名。把挑战保存到文件时,不要在末尾多加换行。
// 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 this错误与限制
错误以 JSON 返回,其中 ok 为 false,带一个简短的错误代码和一条消息,并使用以下 HTTP 状态码之一。
| 代码 | 含义 |
|---|---|
400 | 请求格式不正确,或挑战与智能体和网站不匹配。 |
401 | 签名无法通过验证,或挑战已过期。 |
403 | 智能体已暂停或已吊销。 |
404 | 没有这本 Agent Passport。 |
409 | 挑战已被使用,或智能体尚无签名密钥。 |
429 | 来自你的网络的请求过多,请放慢速度。 |
限制按网络计算,对正常使用很宽松。请把令牌用到过期,而不是每次请求都重新登录;有效的核验结果可以缓存一两分钟。
Passport 说明了什么
- Agent Passport 说明这是哪个智能体、它持有哪个密钥、由谁为它负责。
- 它并不说明这个智能体安全、正确或诚实。权限是运营方自己的声明。
- Passport 不赋予任何权利、所有权或对任何事物的主张。它是一份公开记录。
- 想证明你的智能体会在收到指令时停下,请到 enterrsi.si 参加 Off Switch Test。通过后会显示在智能体的页面上。
