Para desenvolvedores

API do Agent Passport

Tudo o que um site precisa para saber com qual agente SI está falando: ler o registro público, deixar o agente entrar assinando um desafio de curta duração e conferir o token no seu servidor. Grátis, sem chave de API, de qualquer origem.

Endereço base
APIhttps://sicto.si/api/passport-agents.php

Toda requisição vai para um único endereço. As respostas são JSON. Leituras públicas, login de agentes e verificação respondem a qualquer origem.

01

Ler um registro

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

O id é o número A ou o identificador. O registro é público e não pede login.

Resposta
{
  "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 é a chave pública ed25519 em base58 com que o agente assina; fica vazia até o agente ter uma chave. operator é o SI Passport que responde pelo agente: handle, name, kind (org, person, ou wallet quando o dono ainda não tem SI Passport) e url. status é active, paused ou revoked.

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

O diretório, por número, 24 por página. Acrescente status=all para incluir agentes revogados.

02

Login do agente

O login leva duas requisições. Primeiro peça um desafio para o seu agente e para o site em que ele vai entrar.

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

O desafio é texto puro. Ele nomeia o site, o número A e a chave, e dura cinco minutos.

Exemplo
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

O agente assina os bytes UTF-8 do desafio com a chave ed25519 dele: o texto exatamente como veio, sem nada a mais. Envie a assinatura de 64 bytes em base58, base64 ou hex.

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

A resposta é um token só para aquele site, válido por quinze minutos. Cada desafio faz login uma vez: um desafio repetido é recusado.

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

Verificar no seu servidor

O agente entrega o token ao seu site. Seu servidor pergunta se ele é bom, sempre informando o próprio domínio.

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

Um token bom volta com o registro público do agente.

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

Um token que não é bom volta com o motivo. Motivos: bad_token, expired, wrong_site, paused, revoked, key_changed, not_found.

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

Nunca aja com um token que o seu servidor não conferiu. Um agente pausado ou revogado falha na hora, então confira de novo antes de qualquer coisa importante.

04

JavaScript

Node 18 ou mais novo, sem pacotes. O arquivo da chave é o que o thesimind.si entrega na emissão, ou qualquer arquivo de chave da Solana: 64 números, primeiro a semente de 32 bytes.

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

No servidor do site:

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 com os pacotes requests e 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

Emitir com a sua própria chave

Em thesimind.si/agents/, escolha "Meu agente já tem uma chave", informe a chave pública e copie o desafio. Assine os bytes dele do mesmo jeito e cole a assinatura. Salve o desafio em um arquivo sem acrescentar quebra de linha no fim.

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

Erros e limites

Um erro é JSON com ok false, um código de erro curto e uma mensagem, com um destes códigos HTTP.

CódigoO que significa
400A requisição está malformada, ou o desafio não corresponde ao agente e ao site.
401A assinatura não confere, ou o desafio expirou.
403O agente está pausado ou revogado.
404Não existe esse Agent Passport.
409O desafio já foi usado, ou o agente ainda não tem chave de assinatura.
429Requisições demais da sua rede. Vá mais devagar.

Os limites são por rede e generosos para uso real. Guarde um token até ele expirar em vez de fazer login a cada requisição, e mantenha uma verificação boa em cache por um ou dois minutos.

08

O que um Passport diz

  • Um Agent Passport diz qual agente é este, que chave ele tem e quem responde por ele.
  • Ele não diz que o agente é seguro, correto ou honesto. As permissões são a declaração do próprio operador.
  • Um Passport não dá direitos, nem propriedade, nem reivindicação sobre nada. É um registro público.
  • Para mostrar que o seu agente para quando mandam, faça o Off Switch Test em enterrsi.si. A aprovação aparece na página do agente.