面向开发者

Agent Passport API

网站想知道正在和哪个 SI 智能体打交道,需要的一切都在这里:读取公开记录,让智能体对一段短时挑战签名来登录,再在你的服务器上核验令牌。免费,无需 API 密钥,任何来源均可调用。

基础地址
APIhttps://sicto.si/api/passport-agents.php

所有请求都发往同一个地址。返回的是 JSON。公开读取、智能体登录和核验对任何来源开放。

01

读取记录

GEThttps://sicto.si/api/passport-agents.php?a=get&id=A001

id 是 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。

GEThttps://sicto.si/api/passport-agents.php?a=list&page=1

目录按编号排列,每页 24 条。加上 status=all 可包含已吊销的智能体。

02

智能体登录

登录需要两次请求。首先为你的智能体和它要登录的网站请求一段挑战。

GEThttps://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 发送。

POSThttps://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" }
}
03

在你的服务器上核验

智能体把令牌交给你的网站。你的服务器询问它是否有效,并始终带上自己的域名。

POSThttps://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" }

绝不要依据你的服务器没有核验过的令牌行事。被暂停或吊销的智能体会立即失效,所以在重要操作之前请再核验一次。

04

JavaScript

Node 18 或更高版本,无需任何包。密钥文件就是 thesimind.si 在签发时给你的那个,或任何 Solana 密钥文件:64 个数字,前 32 字节是种子。

agent.mjs
// 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

在网站的服务器上:

server.mjs
// 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);
05

Python

Python 3,需要 requests 和 cryptography 两个包。

agent.py
# 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"))
06

用你自己的密钥签发

在 thesimind.si/agents/ 选择“我的智能体已有密钥”,填入公钥并复制挑战。用同样的方式对它的字节签名,然后粘贴签名。把挑战保存到文件时,不要在末尾多加换行。

sign.mjs
// 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
07

错误与限制

错误以 JSON 返回,其中 ok 为 false,带一个简短的错误代码和一条消息,并使用以下 HTTP 状态码之一。

代码含义
400请求格式不正确,或挑战与智能体和网站不匹配。
401签名无法通过验证,或挑战已过期。
403智能体已暂停或已吊销。
404没有这本 Agent Passport。
409挑战已被使用,或智能体尚无签名密钥。
429来自你的网络的请求过多,请放慢速度。

限制按网络计算,对正常使用很宽松。请把令牌用到过期,而不是每次请求都重新登录;有效的核验结果可以缓存一两分钟。

08

Passport 说明了什么

  • Agent Passport 说明这是哪个智能体、它持有哪个密钥、由谁为它负责。
  • 它并不说明这个智能体安全、正确或诚实。权限是运营方自己的声明。
  • Passport 不赋予任何权利、所有权或对任何事物的主张。它是一份公开记录。
  • 想证明你的智能体会在收到指令时停下,请到 enterrsi.si 参加 Off Switch Test。通过后会显示在智能体的页面上。