Geliştiriciler için

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.

Temel adres
APIhttps://sicto.si/api/passport-agents.php

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

01

Bir kaydı okuyun

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

id, A numarası ya da kullanıcı adıdır. Kayıt herkese açıktır ve giriş gerektirmez.

Yanıt
{
  "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.

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

Dizin, numara sırasıyla, sayfa başına 24 kayıt. İptal edilen ajanları da görmek için status=all ekleyin.

02

Ajan girişi

Giriş iki istek sürer. Önce ajanınız ve giriş yapacağı site için bir sorgu isteyin.

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

Sorgu düz metindir. Siteyi, A numarasını ve anahtarı belirtir ve beş dakika geçerlidir.

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

POSThttps://sicto.si/api/passport-agents.php?a=signin
İstek
{
  "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.

Yanıt
{
  "ok": true,
  "token": "sia1.<...>",
  "expires": "2026-11-12T10:15:07Z",
  "site": "example.com",
  "agent": { "id": "A007", "handle": "...", "name": "...", "status": "active", "...": "the public record" }
}
03

Sunucunuzda doğrulayın

Ajan tokenı sitenize verir. Sunucunuz, her zaman kendi alan adını belirterek tokenın geçerli olup olmadığını sorar.

POSThttps://sicto.si/api/passport-agents.php?a=verify
İstek
{ "token": "sia1.<...>", "site": "example.com" }

Geçerli bir token, ajanın herkese açık kaydıyla birlikte döner.

Yanıt
{ "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.

Yanıt
{ "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.

04

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

Sitenin sunucusunda:

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

requests ve cryptography paketleriyle Python 3.

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

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

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

KodAnlamı
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ş.
403Ajan duraklatılmış ya da iptal edilmiş.
404Böyle bir Agent Passport yok.
409Sorgu zaten kullanılmış ya da ajanın henüz imza anahtarı yok.
429Ağı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.

08

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.