Agent Passport API
Bir sitenin hangi SI ajanıyla konuştuğunu bilmesi için gereken her şey: herkese açık kaydı okuyun, ajanın kısa ömürlü bir sorguyu imzalayarak giriş yapmasını sağlayın ve tokenı sunucunuzda kontrol edin. Ücretsiz, API anahtarı yok, her origin'den.
https://sicto.si/api/passport-agents.phpHer istek tek bir adrese gider. Yanıtlar JSON'dur. Herkese açık okumalar, ajan girişi ve doğrulama her origin'e yanıt verir.
Bir kaydı okuyun
https://sicto.si/api/passport-agents.php?a=get&id=A001id, A numarası ya da kullanıcı adıdır. Kayıt herkese açıktır ve giriş gerektirmez.
{
"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, ajanın imzaladığı base58 biçimindeki ed25519 açık anahtarıdır; ajanın anahtarı olana kadar boştur. operator, ajandan sorumlu SI Passport'tur: handle, name, kind (org, person ya da sahibinin henüz SI Passport'u yoksa wallet) ve url. status active, paused ya da revoked olur.
https://sicto.si/api/passport-agents.php?a=list&page=1Dizin, numara sırasıyla, sayfa başına 24 kayıt. İptal edilen ajanları da görmek için status=all ekleyin.
Ajan girişi
Giriş iki istek sürer. Önce ajanınız ve giriş yapacağı site için bir sorgu isteyin.
https://sicto.si/api/passport-agents.php?a=nonce&id=A007&site=example.comSorgu düz metindir. Siteyi, A numarasını ve anahtarı belirtir ve beş dakika geçerlidir.
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
Ajan, sorgunun UTF-8 baytlarını ed25519 anahtarıyla imzalar: metin verildiği gibi, hiçbir şey eklenmeden. 64 baytlık imzayı base58, base64 ya da hex olarak gönderin.
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>"
}Yanıt, yalnızca o site için on beş dakika geçerli bir tokendır. Her sorgu bir kez giriş yaptırır: tekrar kullanılan sorgu reddedilir.
{
"ok": true,
"token": "sia1.<...>",
"expires": "2026-11-12T10:15:07Z",
"site": "example.com",
"agent": { "id": "A007", "handle": "...", "name": "...", "status": "active", "...": "the public record" }
}Sunucunuzda doğrulayın
Ajan tokenı sitenize verir. Sunucunuz, her zaman kendi alan adını belirterek tokenın geçerli olup olmadığını sorar.
https://sicto.si/api/passport-agents.php?a=verify{ "token": "sia1.<...>", "site": "example.com" }Geçerli bir token, ajanın herkese açık kaydıyla birlikte döner.
{ "ok": true, "valid": true, "site": "example.com", "expires": "2026-11-12T10:15:07Z", "agent": { "id": "A007", "...": "the public record" } }Geçerli olmayan bir token nedeniyle birlikte döner. Nedenler: bad_token, expired, wrong_site, paused, revoked, key_changed, not_found.
{ "ok": true, "valid": false, "reason": "paused" }Sunucunuzun kontrol etmediği bir tokena göre asla işlem yapmayın. Duraklatılan ya da iptal edilen ajan hemen başarısız olur; önemli her şeyden önce yeniden kontrol edin.
JavaScript
Node 18 ya da üstü, paket gerekmez. Anahtar dosyası, thesimind.si'nin düzenleme sırasında verdiği dosya ya da herhangi bir Solana anahtar dosyasıdır: 64 sayı, önce 32 baytlık tohum.
// 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 siteSitenin sunucusunda:
// 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
requests ve cryptography paketleriyle Python 3.
# 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"))Kendi anahtarınızla düzenleyin
thesimind.si/agents/ sayfasında "Ajanımın anahtarı var" seçeneğini seçin, açık anahtarı verin ve sorguyu kopyalayın. Baytlarını aynı şekilde imzalayıp imzayı yapıştırın. Sorguyu, sonuna satır sonu eklemeden bir dosyaya kaydedin.
// 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 thisHatalar ve sınırlar
Hata; ok false, kısa bir hata kodu ve bir mesaj içeren JSON'dur ve şu HTTP kodlarından biriyle gelir.
| Kod | Anlamı |
|---|---|
400 | İstek düzgün biçimlenmemiş ya da sorgu ajanla ve siteyle eşleşmiyor. |
401 | İmza doğrulanmıyor ya da sorgunun süresi dolmuş. |
403 | Ajan duraklatılmış ya da iptal edilmiş. |
404 | Böyle bir Agent Passport yok. |
409 | Sorgu zaten kullanılmış ya da ajanın henüz imza anahtarı yok. |
429 | Ağınızdan çok fazla istek geldi. Yavaşlayın. |
Sınırlar ağ başınadır ve gerçek kullanım için cömerttir. Her istekte giriş yapmak yerine tokenı süresi dolana kadar saklayın ve geçerli bir doğrulama yanıtını bir iki dakika önbellekte tutun.
Bir Passport ne söyler
- Agent Passport, bunun hangi ajan olduğunu, hangi anahtarı tuttuğunu ve ondan kimin sorumlu olduğunu söyler.
- Ajanın güvenli, doğru ya da dürüst olduğunu söylemez. İzinler operatörün kendi beyanıdır.
- Bir Passport hiçbir hak, sahiplik ya da talep vermez. Herkese açık bir kayıttır.
- Ajanınızın söylendiğinde durduğunu göstermek için enterrsi.si üzerindeki Off Switch Test'e girin. Geçilen test ajanın sayfasında görünür.
