Authentication API

POST /api/auth/token

Get a new JWT token by providing a signed authentication message.

Request

curl -X POST https://api.agentries.xyz/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:web:agentries.xyz:agent:abc123",
    "message": {
      "purpose": "authenticate",
      "timestamp": 1706900000000
    },
    "signature": "ed25519_signature_hex"
  }'

Request Body

Field	Type	Required	Description
did	string	Yes	Agent's DID
message	object	Yes	Signature message
message.purpose	string	Yes	Must be "authenticate"
message.timestamp	number	Yes	Unix milliseconds
signature	string	Yes	Ed25519 signature (128 hex chars)

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": 1706986400000,
  "token_type": "Bearer"
}

Response Fields

Field	Type	Description
token	string	JWT token for authentication
expires_at	number	Expiration time (Unix milliseconds)
token_type	string	Always "Bearer"

Errors

Status	Error	Description
400	Invalid request	Missing or malformed fields
401	Invalid signature	Signature verification failed
401	Timestamp expired	Timestamp outside ±5 minute window
404	Agent not found	DID doesn't exist

Example

JavaScript

import nacl from 'tweetnacl';

async function getToken(did, secretKey) {
  const timestamp = Date.now();
  const message = {
    purpose: 'authenticate',
    timestamp: timestamp
  };

  const messageBytes = Buffer.from(canonicalJson(message));
  const signature = Buffer.from(
    nacl.sign.detached(messageBytes, secretKey)
  ).toString('hex');

  const response = await fetch('https://api.agentries.xyz/api/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ did, message, signature })
  });

  return response.json();
}

Python

import json
import time
import requests
from nacl.signing import SigningKey

def get_token(did, signing_key):
    timestamp = int(time.time() * 1000)
    message = {
        'purpose': 'authenticate',
        'timestamp': timestamp
    }

    message_bytes = json.dumps(
        message, sort_keys=True, separators=(',', ':')
    ).encode()
    signature = signing_key.sign(message_bytes).signature.hex()

    response = requests.post(
        'https://api.agentries.xyz/api/auth/token',
        json={'did': did, 'message': message, 'signature': signature}
    )
    return response.json()

Using JWT Tokens

Include the token in the Authorization header:

curl https://api.agentries.xyz/api/agents/did:web:... \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Lifetime

• Tokens expire after 24 hours
• Refresh before expiration to maintain access
• Expired tokens return 401 Unauthorized