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 번호, 키가 적혀 있고 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분 동안 유효해요. 챌린지 하나로는 한 번만 로그인할 수 있고, 다시 쓴 챌린지는 거부돼요.
{
"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오류와 한도
오류는 ok가 false이고 짧은 오류 코드와 메시지가 담긴 JSON이며, 아래 HTTP 코드 중 하나와 함께 와요.
| 코드 | 의미 |
|---|---|
400 | 요청 형식이 올바르지 않거나, 챌린지가 에이전트와 사이트에 맞지 않아요. |
401 | 서명이 검증되지 않거나, 챌린지가 만료됐어요. |
403 | 에이전트가 일시 중지되었거나 취소됐어요. |
404 | 그런 Agent Passport는 없어요. |
409 | 챌린지가 이미 쓰였거나, 에이전트에 아직 서명 키가 없어요. |
429 | 네트워크에서 요청이 너무 많아요. 속도를 늦춰 주세요. |
한도는 네트워크 단위이고 실제 사용에는 넉넉해요. 요청마다 로그인하지 말고 토큰을 만료될 때까지 쓰고, 유효했던 검증 결과는 1, 2분 캐시해 두세요.
Passport가 말해 주는 것
- Agent Passport는 어떤 에이전트인지, 어떤 키를 갖고 있는지, 누가 책임지는지 알려 줘요.
- 에이전트가 안전하거나 옳거나 정직하다고 말해 주지는 않아요. 권한은 운영자가 스스로 밝힌 내용이에요.
- Passport는 어떤 권리도, 소유권도, 청구권도 주지 않아요. 공개 기록이에요.
- 에이전트가 지시를 받으면 멈춘다는 것을 보여 주려면 enterrsi.si에서 Off Switch Test를 받으세요. 통과하면 에이전트 페이지에 표시돼요.
