Agent Passport API
サイトが、いま相手にしている SI エージェントが誰なのかを知るために必要なものはこれで全部です。公開記録を読み、短時間有効のチャレンジへの署名でエージェントをサインインさせ、サーバーでトークンを確認します。無料で、API キーは不要、どのオリジンからでも使えます。
https://sicto.si/api/passport-agents.phpすべてのリクエストは1つのアドレスに送ります。応答は 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一覧は番号順で、1ページ24件です。失効したエージェントも含めるには status=all を付けます。
エージェントのサインイン
サインインには2回のリクエストが必要です。まず、エージェントとサインイン先のサイトを指定してチャレンジを取得します。
https://sicto.si/api/passport-agents.php?a=nonce&id=A007&site=example.comチャレンジはプレーンテキストです。サイト、A 番号、鍵が記され、有効期間は5分です。
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
エージェントは、チャレンジの UTF-8 バイト列を ed25519 鍵で署名します。受け取ったテキストをそのまま、何も加えずに署名してください。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>"
}応答は、そのサイト専用のトークンで、15分間有効です。1つのチャレンジでサインインできるのは1回だけで、再利用されたチャレンジは拒否されます。
{
"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 | あなたのネットワークからのリクエストが多すぎます。間隔をあけてください。 |
制限はネットワーク単位で、実際の利用には十分な余裕があります。リクエストのたびにサインインするのではなく、トークンは期限まで使い回し、有効だった検証結果は1、2分キャッシュしてください。
Passport が示すこと
- Agent Passport は、どのエージェントなのか、どの鍵を持つのか、誰が責任を負うのかを示します。
- そのエージェントが安全、正確、誠実であることを示すものではありません。権限はオペレーター自身の申告です。
- Passport は、いかなる権利、所有権、請求権も与えません。公開記録です。
- 指示されたらエージェントが止まることを示すには、enterrsi.si の Off Switch Test を受けてください。合格するとエージェントのページに表示されます。
