openbotauth

openbotauth

Cryptographic identity for AI agents. Register once, then sign HTTP requests (RFC 9421) anywhere. Optional browser integrations via per-request signing proxy.

When to trigger

User wants to: browse websites with signed identity, authenticate a browser session, sign HTTP requests as a bot, set up OpenBotAuth headers, prove human-vs-bot session origin, manage agent keys, sign scraping sessions, register with OBA registry, set up enterprise SSO for agents.

Tools

Bash

Instructions

This skill is self-contained — no npm packages required. Core mode uses Node.js (v18+) + curl; proxy mode additionally needs openssl.

Compatibility Modes

Core Mode (portable, recommended):

• Works with: Claude Code, Cursor, Codex CLI, Goose, any shell-capable agent
• Uses: Node.js crypto + curl for registration
• Token needed only briefly for POST /agents

Browser Mode (optional, runtime-dependent):

• For: agent-browser, OpenClaw Browser Relay, CUA tooling
• Bearer token must NOT live inside the browsing runtime
• Do registration in CLI mode first, then browse with signatures only

Key Storage

Keys are stored at ~/.config/openbotauth/key.json in OBA's canonical format:

{
  "kid": "<thumbprint-based-id>",
  "x": "<base64url-raw-public-key>",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...",
  "privateKeyPem": "-----BEGIN PRIVATE KEY-----\n...",
  "createdAt": "..."
}

The OBA token lives at ~/.config/openbotauth/token (chmod 600).

Agent registration info (agent_id, JWKS URL) should be saved in agent memory/notes after Step 3.

Token Handling Contract

The bearer token is for registration only:

• Use it ONLY for POST /agents (and key rotation)
• Delete ~/.config/openbotauth/token after registration completes
• Never attach bearer tokens to browsing sessions

Minimum scopes: agents:write + profile:read

• Only add keys:write if you need /keys endpoint

Never use global headers with OBA token:

• agent-browser's set headers command applies headers globally
• Use origin-scoped headers only (via open --headers)

---

Step 1: Check for existing identity

cat ~/.config/openbotauth/key.json 2>/dev/null && echo "---KEY EXISTS---" || echo "---NO KEY FOUND---"

If a key exists: read it to extract kid, x, and privateKeyPem. Check if the agent is already registered (look for agent_id in memory/notes). If registered, skip to Step 4 (signing).

If no key exists: proceed to Step 2.

---

Step 2: Generate Ed25519 keypair (if no key exists)

Run this locally. Nothing leaves the machine.

node -e "
const crypto = require('node:crypto');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');

const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();

// Derive kid from JWK thumbprint (matches OBA's format)
const spki = publicKey.export({ type: 'spki', format: 'der' });
if (spki.length !== 44) throw new Error('Unexpected SPKI length: ' + spki.length);
const rawPub = spki.subarray(12, 44);
const x = rawPub.toString('base64url');
const thumbprint = JSON.stringify({ kty: 'OKP', crv: 'Ed25519', x });
const hash = crypto.createHash('sha256').update(thumbprint).digest();
const kid = hash.toString('base64url').slice(0, 16);

const dir = path.join(os.homedir(), '.config', 'openbotauth');
fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
fs.writeFileSync(path.join(dir, 'key.json'), JSON.stringify({
  kid, x, publicKeyPem, privateKeyPem,
  createdAt: new Date().toISOString()
}, null, 2), { mode: 0o600 });

console.log('Key generated!');
console.log('kid:', kid);
console.log('x:', x);
"

Save the kid and x values — needed for registration.

---

Step 3: Register with OpenBotAuth (if not yet registered)

This is a one-time setup that gives your agent a public JWKS endpoint for signature verification.

3a. Get a token from the user

Ask the user:

I need an OpenBotAuth token to register my cryptographic identity. Takes 30 seconds:

1. Go to https://openbotauth.org/token
2. Click "Login with GitHub"
3. Copy the token and paste it back to me

The token looks like oba_ followed by 64 hex characters.

When they provide it, save it:

node -e "
const fs = require('node:fs');
const path = require('node:path');
const os = require('node:os');
const dir = path.join(os.homedir(), '.config', 'openbotauth');
fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
const token = process.argv[1].trim();
fs.writeFileSync(path.join(dir, 'token'), token, { mode: 0o600 });
console.log('Token saved.');
" "THE_TOKEN_HERE"

3b. Register the agent

node -e "
const fs = require('node:fs');
const path = require('node:path');
const os = require('node:os');

const dir = path.join(os.homedir(), '.config', 'openbotauth');
const key = JSON.parse(fs.readFileSync(path.join(dir, 'key.json'), 'utf-8'));
const tokenPath = path.join(dir, 'token');
const token = fs.readFileSync(tokenPath, 'utf-8').trim();

const AGENT_NAME = process.argv[1] || 'my-agent';
const API = 'https://api.openbotauth.org';

fetch(API + '/agents', {
  method: 'POST',
  redirect: 'error',  // Never follow redirects with bearer token
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: AGENT_NAME,
    agent_type: 'agent',
    public_key: {
      kty: 'OKP',
      crv: 'Ed25519',
      kid: key.kid,
      x: key.x,
      use: 'sig',
      alg: 'EdDSA'
    }
  })
})
.then(r => { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); })
.then(async d => {
  console.log('Agent registered!');
  console.log('Agent ID:', d.id);

  // Fetch session to get username for JWKS URL
  const session = await fetch(API + '/auth/session', {
    redirect: 'error',  // Never follow redirects with bearer token
    headers: { 'Authorization': 'Bearer ' + token }
  }).then(r => { if (!r.ok) throw new Error('Session HTTP ' + r.status); return r.json(); });
  const username = session.profile?.username || session.user?.github_username;
  if (!username) throw new Error('Could not resolve username from /auth/session');
  const jwksUrl = API + '/jwks/' + username + '.json';

  // Write config.json for the signing proxy
  fs.writeFileSync(path.join(dir, 'config.json'), JSON.stringify({
    agent_id: d.id,
    username: username,
    jwksUrl: jwksUrl
  }, null, 2), { mode: 0o600 });
  console.log('Config written to ~/.config/openbotauth/config.json');

  // Delete token — no longer needed after registration
  fs.unlinkSync(tokenPath);
  console.log('Token deleted (no longer needed)');

  console.log('');
  console.log('JWKS URL:', jwksUrl);
  console.log('');
  console.log('Save this to memory:');
  console.log(JSON.stringify({
    openbotauth: {
      agent_id: d.id,
      kid: key.kid,
      username: username,
      jwks_url: jwksUrl
    }
  }, null, 2));
})
.catch(e => console.error('Registration failed:', e.message));
" "AGENT_NAME_HERE"

3c. Verify registration

curl https://api.openbotauth.org/jwks/YOUR_USERNAME.json

You should see your public key in the keys array. This is the URL that verifiers will use to check your signatures.

Save the agent_id, username, and JWKS URL to memory/notes — you'll need the JWKS URL for the Signature-Agent header in every signed request.

Token Safety Rules

Do	Don't
curl -H "Authorization: Bearer ..." https://api.openbotauth.org/agents	Set bearer token as global browser header
Delete token after registration	Keep token in browsing session
Use origin-scoped headers for signing	Use set headers with bearer tokens
Store token at ~/.config/openbotauth/token (chmod 600)	Paste token into chat logs

---

Step 4: Sign a request

Generate RFC 9421 signed headers for a target URL. The output is a JSON object for agent-browser open --headers or set headers --json (OpenClaw).

Required inputs:

• TARGET_URL — the URL being browsed
• METHOD — HTTP method (GET, POST, etc.)
• JWKS_URL — your JWKS endpoint from Step 3 (the Signature-Agent value)

node -e "
const { createPrivateKey, sign, randomUUID } = require('crypto');
const { readFileSync } = require('fs');
const { join } = require('path');
const { homedir } = require('os');

const METHOD = (process.argv[1] || 'GET').toUpperCase();
const TARGET_URL = process.argv[2];
const JWKS_URL = process.argv[3] || '';

if (!TARGET_URL) { console.error('Usage: node sign.js METHOD URL JWKS_URL'); process.exit(1); }

const key = JSON.parse(readFileSync(join(homedir(), '.config', 'openbotauth', 'key.json'), 'utf-8'));
const url = new URL(TARGET_URL);
const created = Math.floor(Date.now() / 1000);
const expires = created + 300;
const nonce = randomUUID();

// RFC 9421 signature base
const lines = [
  '\"@method\": ' + METHOD,
  '\"@authority\": ' + url.host,
  '\"@path\": ' + url.pathname + url.search
];
const sigInput = '(\"@method\" \"@authority\" \"@path\");created=' + created + ';expires=' + expires + ';nonce=\"' + nonce + '\";keyid=\"' + key.kid + '\";alg=\"ed25519\"';
lines.push('\"@signature-params\": ' + sigInput);

const base = lines.join('\n');
const pk = createPrivateKey(key.privateKeyPem);
const sig = sign(null, Buffer.from(base), pk).toString('base64');

const headers = {
  'Signature': 'sig1=:' + sig + ':',
  'Signature-Input': 'sig1=' + sigInput
};
if (JWKS_URL) {
  headers['Signature-Agent'] = JWKS_URL;
}

console.log(JSON.stringify(headers));
" "METHOD" "TARGET_URL" "JWKS_URL"

Replace the arguments:

• METHOD — e.g., GET
• TARGET_URL — e.g., https://example.com/page
• JWKS_URL — e.g., https://api.openbotauth.org/jwks/your-username.json

**For st

---

Content truncated.