API Agent Passport
Mọi thứ một trang web cần để biết mình đang nói chuyện với tác tử SI nào: đọc hồ sơ công khai, cho tác tử đăng nhập bằng cách ký một thử thách ngắn hạn, rồi kiểm tra token trên máy chủ của bạn. Miễn phí, không cần khóa API, từ mọi origin.
https://sicto.si/api/passport-agents.phpMọi yêu cầu đều gửi tới một địa chỉ. Phản hồi là JSON. Các lượt đọc công khai, đăng nhập tác tử và xác minh trả lời mọi origin.
Đọc một hồ sơ
https://sicto.si/api/passport-agents.php?a=get&id=A001id là số A hoặc định danh. Hồ sơ là công khai và không cần đăng nhập.
{
"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 là khóa công khai ed25519 dạng base58 mà tác tử dùng để ký; nó để trống cho tới khi tác tử có khóa. operator là SI Passport chịu trách nhiệm cho tác tử: handle, name, kind (org, person, hoặc wallet khi chủ sở hữu chưa có SI Passport) và url. status là active, paused hoặc revoked.
https://sicto.si/api/passport-agents.php?a=list&page=1Danh bạ, theo số, 24 mục mỗi trang. Thêm status=all để gồm cả tác tử đã bị thu hồi.
Đăng nhập tác tử
Đăng nhập cần hai yêu cầu. Trước hết, xin một thử thách cho tác tử của bạn và trang mà nó đăng nhập.
https://sicto.si/api/passport-agents.php?a=nonce&id=A007&site=example.comThử thách là văn bản thuần. Nó nêu tên trang, số A và khóa, và có hiệu lực năm phút.
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
Tác tử ký các byte UTF-8 của thử thách bằng khóa ed25519 của nó: đúng văn bản đã nhận, không thêm gì. Gửi chữ ký 64 byte dưới dạng base58, base64 hoặc 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>"
}Kết quả là một token chỉ dùng cho trang đó, có hiệu lực mười lăm phút. Mỗi thử thách chỉ đăng nhập được một lần: thử thách dùng lại sẽ bị từ chối.
{
"ok": true,
"token": "sia1.<...>",
"expires": "2026-11-12T10:15:07Z",
"site": "example.com",
"agent": { "id": "A007", "handle": "...", "name": "...", "status": "active", "...": "the public record" }
}Xác minh trên máy chủ
Tác tử đưa token cho trang của bạn. Máy chủ của bạn hỏi token có hợp lệ không, luôn kèm tên miền của chính mình.
https://sicto.si/api/passport-agents.php?a=verify{ "token": "sia1.<...>", "site": "example.com" }Token hợp lệ được trả về cùng hồ sơ công khai của tác tử.
{ "ok": true, "valid": true, "site": "example.com", "expires": "2026-11-12T10:15:07Z", "agent": { "id": "A007", "...": "the public record" } }Token không hợp lệ được trả về cùng lý do. Lý do: bad_token, expired, wrong_site, paused, revoked, key_changed, not_found.
{ "ok": true, "valid": false, "reason": "paused" }Đừng bao giờ hành động theo một token mà máy chủ của bạn chưa kiểm tra. Tác tử bị tạm dừng hoặc thu hồi sẽ thất bại ngay, nên hãy kiểm tra lại trước mọi việc quan trọng.
JavaScript
Node 18 trở lên, không cần gói nào. Tệp khóa là tệp thesimind.si đưa cho bạn khi cấp, hoặc bất kỳ tệp khóa Solana nào: 64 số, 32 byte hạt giống đứng trước.
// 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 siteTrên máy chủ của trang:
// 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 với các gói requests và 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"))Cấp bằng khóa của riêng bạn
Tại thesimind.si/agents/, chọn "Tác tử của tôi đã có khóa", nhập khóa công khai và sao chép thử thách. Ký các byte của nó theo cùng cách rồi dán chữ ký. Lưu thử thách vào tệp mà không thêm dấu xuống dòng ở cuối.
// 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 thisLỗi và giới hạn
Lỗi là JSON với ok false, một mã lỗi ngắn và một thông báo, kèm một trong các mã HTTP sau.
| Mã | Ý nghĩa |
|---|---|
400 | Yêu cầu không đúng định dạng, hoặc thử thách không khớp với tác tử và trang. |
401 | Chữ ký không xác minh được, hoặc thử thách đã hết hạn. |
403 | Tác tử đang tạm dừng hoặc đã bị thu hồi. |
404 | Không có Agent Passport như vậy. |
409 | Thử thách đã được dùng, hoặc tác tử chưa có khóa ký. |
429 | Quá nhiều yêu cầu từ mạng của bạn. Hãy chậm lại. |
Giới hạn tính theo mạng và rộng rãi cho nhu cầu thật. Hãy giữ token cho tới khi hết hạn thay vì đăng nhập ở mỗi yêu cầu, và lưu kết quả xác minh hợp lệ trong một hai phút.
Passport nói lên điều gì
- Agent Passport cho biết đây là tác tử nào, nó giữ khóa nào và ai chịu trách nhiệm cho nó.
- Nó không nói rằng tác tử an toàn, đúng đắn hay trung thực. Các quyền là lời khai của chính người vận hành.
- Passport không trao quyền lợi, quyền sở hữu hay yêu sách với bất cứ thứ gì. Nó là một hồ sơ công khai.
- Để cho thấy tác tử của bạn dừng khi được lệnh, hãy làm Off Switch Test trên enterrsi.si. Kết quả đạt sẽ hiện trên trang của tác tử.
