For builders

Agent Passport API

Everything a site needs to know which SI agent it is talking to: read the public record, let the agent sign in by signing a short-lived challenge, and check the token on your server. Free, no API key, any origin.

Base address
APIhttps://sicto.si/api/passport-agents.php

Every request goes to one address. Answers are JSON. Public reads, agent sign-in and verify answer any origin.

01

Read a record

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

The id is the A number or the handle. The record is public and needs no sign-in.

Answer
{
  "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 is the base58 ed25519 public key the agent signs with; it is empty until the agent has a key. operator is the SI Passport that answers for the agent: its handle, name, kind (org, person, or wallet when the owner has no SI Passport yet) and url. status is active, paused or revoked.

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

The directory, by number, 24 to a page. Add status=all to include revoked agents.

02

Agent sign-in

Sign-in takes two requests. First ask for a challenge for your agent and the site it is signing in to.

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

The challenge is plain text. It names the site, the A number and the key, and it lasts five minutes.

Example
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

The agent signs the UTF-8 bytes of the challenge with its ed25519 key: the text exactly as given, with nothing added. Send the 64 byte signature as base58, base64 or hex.

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

The answer is a token for that site only, good for fifteen minutes. Each challenge signs in once: a replayed challenge is refused.

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

Verify on your server

The agent hands the token to your site. Your server asks whether it is good, always naming its own domain.

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

A good token comes back with the public record of the agent.

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

A token that is not good comes back with the reason. Reasons: bad_token, expired, wrong_site, paused, revoked, key_changed, not_found.

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

Never act on a token your server has not checked. A paused or revoked agent fails at once, so check again before anything that matters.

04

JavaScript

Node 18 or newer, no packages. The key file is the one thesimind.si gives you at issue, or any Solana key file: 64 numbers, the 32 byte seed first.

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

On the site's server:

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 with the requests and cryptography packages.

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

Issue with your own key

On thesimind.si/agents/, choose "My agent has a key", give the public key and copy the challenge. Sign its bytes the same way and paste the signature. Save the challenge to a file with no line break added at the end.

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

Errors and limits

An error is JSON with ok false, a short error code and a message, with one of these HTTP codes.

CodeWhat it means
400The request is not well formed, or the challenge does not match the agent and site.
401The signature does not verify, or the challenge has expired.
403The agent is paused or revoked.
404There is no such Agent Passport.
409The challenge was already used, or the agent has no signing key yet.
429Too many requests from your network. Slow down.

Limits are per network and generous for real use. Keep a token until it expires instead of signing in for every request, and cache a good verify answer for a minute or two.

08

What a Passport says

  • An Agent Passport says which agent this is, which key it holds and who answers for it.
  • It does not say the agent is safe, right or honest. Permissions are the operator's own statement.
  • A Passport gives no rights, no ownership and no claim on anything. It is a public record.
  • To show that your agent stops when told, take the Off Switch Test on enterrsi.si. A pass shows on the agent's page.