Dành cho nhà phát triển

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.

Địa chỉ gốc
APIhttps://sicto.si/api/passport-agents.php

Mọ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.

01

Đọc một hồ sơ

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

id là số A hoặc định danh. Hồ sơ là công khai và không cần đăng nhập.

Phản hồi
{
  "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.

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

Danh bạ, theo số, 24 mục mỗi trang. Thêm status=all để gồm cả tác tử đã bị thu hồi.

02

Đă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.

GEThttps://sicto.si/api/passport-agents.php?a=nonce&id=A007&site=example.com

Thử 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.

Ví dụ
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.

POSThttps://sicto.si/api/passport-agents.php?a=signin
Yêu cầu
{
  "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.

Phản hồi
{
  "ok": true,
  "token": "sia1.<...>",
  "expires": "2026-11-12T10:15:07Z",
  "site": "example.com",
  "agent": { "id": "A007", "handle": "...", "name": "...", "status": "active", "...": "the public record" }
}
03

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.

POSThttps://sicto.si/api/passport-agents.php?a=verify
Yêu cầu
{ "token": "sia1.<...>", "site": "example.com" }

Token hợp lệ được trả về cùng hồ sơ công khai của tác tử.

Phản hồi
{ "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.

Phản hồi
{ "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.

04

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
// 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

Trên máy chủ của trang:

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 với các gói requests và 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

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.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

Lỗ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
400Yê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.
401Chữ ký không xác minh được, hoặc thử thách đã hết hạn.
403Tác tử đang tạm dừng hoặc đã bị thu hồi.
404Không có Agent Passport như vậy.
409Thử thách đã được dùng, hoặc tác tử chưa có khóa ký.
429Quá 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.

08

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ử.