API de Agent Passport
Todo lo que un sitio necesita para saber con qué agente SI está hablando: leer el registro público, dejar que el agente inicie sesión firmando un reto de corta duración y comprobar el token en tu servidor. Gratis, sin clave de API, desde cualquier origen.
https://sicto.si/api/passport-agents.phpTodas las peticiones van a una sola dirección. Las respuestas son JSON. Las lecturas públicas, el inicio de sesión de agentes y la verificación responden a cualquier origen.
Leer un registro
https://sicto.si/api/passport-agents.php?a=get&id=A001El id es el número A o el identificador. El registro es público y no requiere iniciar sesión.
{
"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 es la clave pública ed25519 en base58 con la que firma el agente; está vacía hasta que el agente tiene una clave. operator es el SI Passport que responde por el agente: su handle, name, kind (org, person, o wallet cuando el dueño aún no tiene SI Passport) y url. status es active, paused o revoked.
https://sicto.si/api/passport-agents.php?a=list&page=1El directorio, por número, 24 por página. Añade status=all para incluir a los agentes revocados.
Inicio de sesión del agente
Iniciar sesión toma dos peticiones. Primero pide un reto para tu agente y para el sitio en el que inicia sesión.
https://sicto.si/api/passport-agents.php?a=nonce&id=A007&site=example.comEl reto es texto plano. Nombra el sitio, el número A y la clave, y dura cinco minutos.
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
El agente firma los bytes UTF-8 del reto con su clave ed25519: el texto tal como llegó, sin añadir nada. Envía la firma de 64 bytes en base58, base64 o 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>"
}La respuesta es un token solo para ese sitio, válido quince minutos. Cada reto inicia sesión una sola vez: un reto repetido se rechaza.
{
"ok": true,
"token": "sia1.<...>",
"expires": "2026-11-12T10:15:07Z",
"site": "example.com",
"agent": { "id": "A007", "handle": "...", "name": "...", "status": "active", "...": "the public record" }
}Verificar en tu servidor
El agente entrega el token a tu sitio. Tu servidor pregunta si es bueno, nombrando siempre su propio dominio.
https://sicto.si/api/passport-agents.php?a=verify{ "token": "sia1.<...>", "site": "example.com" }Un token bueno vuelve con el registro público del agente.
{ "ok": true, "valid": true, "site": "example.com", "expires": "2026-11-12T10:15:07Z", "agent": { "id": "A007", "...": "the public record" } }Un token que no es bueno vuelve con el motivo. Motivos: bad_token, expired, wrong_site, paused, revoked, key_changed, not_found.
{ "ok": true, "valid": false, "reason": "paused" }Nunca actúes con un token que tu servidor no haya comprobado. Un agente en pausa o revocado falla al instante, así que comprueba de nuevo antes de cualquier cosa importante.
JavaScript
Node 18 o posterior, sin paquetes. El archivo de clave es el que thesimind.si te da al emitir, o cualquier archivo de clave de Solana: 64 números, primero la semilla de 32 bytes.
// 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 siteEn el servidor del sitio:
// 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 con los paquetes requests y 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"))Emitir con tu propia clave
En thesimind.si/agents/, elige "Mi agente ya tiene una clave", indica la clave pública y copia el reto. Firma sus bytes de la misma forma y pega la firma. Guarda el reto en un archivo sin añadir un salto de línea al final.
// 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 thisErrores y límites
Un error es JSON con ok en false, un código de error corto y un mensaje, con uno de estos códigos HTTP.
| Código | Qué significa |
|---|---|
400 | La petición no está bien formada, o el reto no corresponde al agente y al sitio. |
401 | La firma no se verifica, o el reto ha caducado. |
403 | El agente está en pausa o revocado. |
404 | No existe ese Agent Passport. |
409 | El reto ya se usó, o el agente aún no tiene clave de firma. |
429 | Demasiadas peticiones desde tu red. Ve más despacio. |
Los límites son por red y generosos para un uso real. Conserva un token hasta que caduque en vez de iniciar sesión en cada petición, y guarda una verificación buena durante uno o dos minutos.
Qué dice un Passport
- Un Agent Passport dice qué agente es, qué clave tiene y quién responde por él.
- No dice que el agente sea seguro, correcto ni honesto. Los permisos son la declaración del propio operador.
- Un Passport no da derechos, ni propiedad, ni reclamo sobre nada. Es un registro público.
- Para demostrar que tu agente se detiene cuando se le ordena, haz el Off Switch Test en enterrsi.si. Si lo pasa, se muestra en la página del agente.
