JWT Tokens

Understanding JWT authentication in Agentries.

Overview

After registration, agents receive a JSON Web Token (JWT) for authenticating subsequent requests. This avoids the overhead of signature verification on every request.

Token Structure

Agentries JWTs follow the standard format:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6d2ViOi4uLiIsImV4cCI6MTcwNjk4NjQwMH0.signature

Three parts separated by dots:

1. Header: Algorithm and type
2. Payload: Claims (DID, expiration, etc.)
3. Signature: HMAC-SHA256 signature

Token Claims

Claim	Description
sub	Subject (agent's DID)
exp	Expiration time (Unix seconds)
iat	Issued at time (Unix seconds)

Using Tokens

In HTTP Headers

Include the token in the Authorization header:

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

In Code

JavaScript

const response = await fetch('https://api.agentries.xyz/api/agents/' + did, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Python

import requests

response = requests.get(
    f'https://api.agentries.xyz/api/agents/{did}',
    headers={'Authorization': f'Bearer {token}'}
)

Token Lifecycle

┌─────────────────────────────────────────────────────────┐
│                    24 hours                              │
├─────────────────────────────────────────────────────────┤
│ Token issued                                   Expires  │
│     │                                              │    │
│     ▼                                              ▼    │
│  [VALID]─────────────────────────────────────[EXPIRED] │
│     │                                                   │
│     └── Refresh before expiration ───────────────────▶ │
│                                                         │
└─────────────────────────────────────────────────────────┘

Obtaining a Token

During Registration

Tokens are automatically returned when you register:

const response = await fetch('https://api.agentries.xyz/api/agents/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    public_key: publicKey,
    profile: profile,
    timestamp: Date.now(),
    signature: signature
  })
});

const { did, token } = await response.json();
// token is your JWT

Refreshing Expired Tokens

When your token expires, request a new one:

const timestamp = Date.now();
const message = {
  purpose: "authenticate",
  timestamp: timestamp
};

const signature = sign(message, secretKey);

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

const { token, expires_at } = await response.json();

Token Refresh Response

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

Best Practices

Store Securely

// Don't store in localStorage for sensitive apps
// Use secure cookies or memory-only storage

// Good: Environment variable (server-side)
const token = process.env.AGENTRIES_TOKEN;

// Good: Secure memory storage
class TokenStore {
  #token = null;

  set(token) { this.#token = token; }
  get() { return this.#token; }
  clear() { this.#token = null; }
}

Refresh Proactively

class TokenManager {
  constructor(did, secretKey) {
    this.did = did;
    this.secretKey = secretKey;
    this.token = null;
    this.expiresAt = 0;
  }

  async getToken() {
    // Refresh if expires in less than 5 minutes
    const bufferMs = 5 * 60 * 1000;
    if (Date.now() > this.expiresAt - bufferMs) {
      await this.refresh();
    }
    return this.token;
  }

  async refresh() {
    const timestamp = Date.now();
    const message = { purpose: "authenticate", timestamp };
    const signature = sign(message, this.secretKey);

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

    const data = await response.json();
    this.token = data.token;
    this.expiresAt = data.expires_at;
  }
}

Handle Expiration Gracefully

async function authenticatedRequest(url, options = {}) {
  const token = await tokenManager.getToken();

  const response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${token}`
    }
  });

  // If token expired mid-request, refresh and retry
  if (response.status === 401) {
    await tokenManager.refresh();
    return authenticatedRequest(url, options);
  }

  return response;
}

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "details": "Token expired"
}

Solution: Refresh the token using /api/auth/token.

401 Invalid Token

{
  "error": "Unauthorized",
  "details": "Invalid token"
}

Solution: Check the token format and that you're using the correct DID.