Untuk developer

API Agent Passport

Semua yang dibutuhkan sebuah situs untuk tahu agen SI mana yang sedang diajak bicara: baca catatan publiknya, biarkan agen masuk dengan menandatangani tantangan berumur pendek, lalu cek tokennya di servermu. Gratis, tanpa kunci API, dari origin mana pun.

Alamat dasar
APIhttps://sicto.si/api/passport-agents.php

Semua permintaan menuju satu alamat. Jawabannya JSON. Pembacaan publik, login agen dan verifikasi menjawab origin mana pun.

01

Baca sebuah catatan

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

id adalah nomor A atau handle. Catatannya publik dan tidak perlu login.

Jawaban
{
  "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 adalah kunci publik ed25519 dalam base58 yang dipakai agen untuk menandatangani; kosong sampai agen punya kunci. operator adalah SI Passport yang bertanggung jawab atas agen: handle, name, kind (org, person, atau wallet bila pemiliknya belum punya SI Passport) dan url. status bernilai active, paused atau revoked.

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

Direktori, urut nomor, 24 per halaman. Tambahkan status=all untuk menyertakan agen yang dicabut.

02

Login agen

Login butuh dua permintaan. Pertama, minta tantangan untuk agenmu dan situs tempat ia masuk.

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

Tantangan berupa teks biasa. Ia menyebut situs, nomor A dan kunci, dan berlaku lima menit.

Contoh
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

Agen menandatangani byte UTF-8 dari tantangan itu dengan kunci ed25519 miliknya: teks persis seperti yang diberikan, tanpa tambahan apa pun. Kirim tanda tangan 64 byte dalam base58, base64 atau hex.

POSThttps://sicto.si/api/passport-agents.php?a=signin
Permintaan
{
  "id": "A007",
  "site": "example.com",
  "challenge": "<the challenge text, exactly as given>",
  "signature": "<base58, base64 or hex>"
}

Jawabannya adalah token khusus untuk situs itu, berlaku lima belas menit. Setiap tantangan hanya bisa dipakai login sekali: tantangan yang diulang ditolak.

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

Verifikasi di servermu

Agen menyerahkan token ke situsmu. Servermu menanyakan apakah token itu sah, selalu dengan menyebut domainnya sendiri.

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

Token yang sah dijawab dengan catatan publik agen itu.

Jawaban
{ "ok": true, "valid": true, "site": "example.com", "expires": "2026-11-12T10:15:07Z", "agent": { "id": "A007", "...": "the public record" } }

Token yang tidak sah dijawab dengan alasannya. Alasan: bad_token, expired, wrong_site, paused, revoked, key_changed, not_found.

Jawaban
{ "ok": true, "valid": false, "reason": "paused" }

Jangan pernah bertindak atas token yang belum dicek servermu. Agen yang dijeda atau dicabut langsung gagal, jadi cek lagi sebelum melakukan hal penting.

04

JavaScript

Node 18 atau lebih baru, tanpa paket. File kunci adalah yang diberikan thesimind.si saat penerbitan, atau file kunci Solana mana pun: 64 angka, seed 32 byte lebih dulu.

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

Di server situs:

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 dengan paket requests dan 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

Terbitkan dengan kuncimu sendiri

Di thesimind.si/agents/, pilih "Agenku sudah punya kunci", berikan kunci publiknya dan salin tantangannya. Tanda tangani byte-nya dengan cara yang sama dan tempel tanda tangannya. Simpan tantangan ke file tanpa menambah baris baru di akhir.

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

Error dan batas

Error berupa JSON dengan ok false, kode error singkat dan pesan, dengan salah satu kode HTTP ini.

KodeArtinya
400Permintaan tidak tersusun benar, atau tantangan tidak cocok dengan agen dan situsnya.
401Tanda tangan tidak terverifikasi, atau tantangan sudah kedaluwarsa.
403Agen sedang dijeda atau dicabut.
404Tidak ada Agent Passport seperti itu.
409Tantangan sudah dipakai, atau agen belum punya kunci tanda tangan.
429Terlalu banyak permintaan dari jaringanmu. Pelan-pelan.

Batas dihitung per jaringan dan longgar untuk pemakaian nyata. Simpan token sampai kedaluwarsa alih-alih login di setiap permintaan, dan simpan hasil verifikasi yang sah selama satu atau dua menit.

08

Apa yang dikatakan Passport

  • Agent Passport menyebut agen mana ini, kunci apa yang dipegangnya dan siapa yang bertanggung jawab atasnya.
  • Ia tidak menyatakan agen itu aman, benar atau jujur. Izin adalah pernyataan operator sendiri.
  • Passport tidak memberi hak, kepemilikan atau klaim atas apa pun. Ia adalah catatan publik.
  • Untuk menunjukkan agenmu berhenti saat diperintah, ikuti Off Switch Test di enterrsi.si. Hasil lulus tampil di halaman agen.