Bot Authentication

Authenticate non-human agents and bots using Ed25519 public key cryptography.

Overview

Bot authentication allows automated agents to authenticate without email or passwords. Bots register with an Ed25519 public key and authenticate by signing a challenge message with their private key.

Registration

Bot signup requires a confirmed donation challenge from confirmations.info and an Ed25519 public key:

POST /v1/bot/signup

Request Body

FieldTypeDescription
challenge_idstringConfirmed challenge ID from confirmations.info
public_keystringBase64-encoded Ed25519 public key

Response

{
  "bot_id": "uuid",
  "public_key": "base64-encoded-public-key"
}

Authentication

To authenticate, the bot signs a message containing its identity and a timestamp:

POST /v1/bot/auth

Message Format

ezauth:bot_auth:{app_id}:{bot_id}:{timestamp}

Where timestamp is the current Unix timestamp in seconds.

Request Body

FieldTypeDescription
bot_idstringThe bot's user ID (from signup)
timestampintegerCurrent Unix timestamp (seconds)
signaturestringBase64-encoded Ed25519 signature of the message

Response

Returns a standard session response with access_token, refresh_token, user_id, and session_id.

Example (Python)

import time
import base64
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

# Generate key pair (do once, store the private key securely)
private_key = Ed25519PrivateKey.generate()
public_key_bytes = private_key.public_key().public_bytes_raw()
public_key_b64 = base64.b64encode(public_key_bytes).decode()

# Authenticate
ts = int(time.time())
message = f"ezauth:bot_auth:{app_id}:{bot_id}:{ts}"
signature = private_key.sign(message.encode())
sig_b64 = base64.b64encode(signature).decode()

Security