Getting Started

Learn how to use the Auth-Agent JavaScript/TypeScript SDK for server-side OAuth 2.1 authentication

Getting Started with JavaScript SDK

The Auth-Agent SDK is a complete server-side TypeScript/JavaScript SDK for implementing OAuth 2.1 with PKCE authentication for AI agents.

Installation

npm

npm install ai-auth

yarn add ai-auth

pnpm add ai-auth

Quick Start

1. Initialize the SDK

import { AgentSDK } from "ai-auth";

const sdk = new AgentSDK({
  agentId: "your-agent-id",
  agentSecret: "your-agent-secret", // Optional, for confidential clients
  serverUrl: "https://api.auth-agent.com",
  timeout: 10000,
  onTokensReceived: async (tokens) => {
    // Store tokens in your preferred storage
    await yourStorage.saveTokens(tokens);
  },
  onTokensRefreshed: async (tokens) => {
    // Update stored tokens
    await yourStorage.updateTokens(tokens);
  },
  onTokensRevoked: async () => {
    // Clear stored tokens
    await yourStorage.clearTokens();
  },
});

2. Start OAuth Flow

// Generate authorization URL
const { url, codeVerifier, state } = await sdk.getAuthorizationUrl({
  redirectUri: "https://your-app.com/callback",
  scope: "openid profile email agent",
});

// Redirect user to authorization URL
console.log("Visit:", url);

// Store codeVerifier and state for later use
await storage.save({ codeVerifier, state });

3. Exchange Authorization Code for Tokens

// In your callback handler
const code = req.query.code;
const state = req.query.state;
const redirectUri = "https://your-app.com/callback";

const tokens = await sdk.exchangeCode(code, state, redirectUri);

// Tokens are automatically passed to onTokensReceived callback
// Access token, refresh token, and ID token are now stored

4. Make Authenticated Requests

// Get access token from your storage
const accessToken = await storage.getAccessToken();

// Get user info
const userInfo = await sdk.getUserInfo(accessToken);

// Get agent profile
const profile = await sdk.getAgentProfile(accessToken);

// Send events
await sdk.sendEvent(accessToken, {
  event: "click",
  selector: "#button",
  site: "example.com",
});

5. Refresh Tokens

// When access token expires
const refreshToken = await storage.getRefreshToken();
const newTokens = await sdk.refreshAccessToken(refreshToken);

// New tokens are automatically passed to onTokensRefreshed callback

Using Token Manager

The SDK includes a built-in TokenManager for simple token storage:

import { AgentSDK, TokenManager } from "ai-auth";

const tokenManager = new TokenManager();

const sdk = new AgentSDK({
  agentId: "your-agent-id",
  serverUrl: "https://api.auth-agent.com",
  onTokensReceived: (tokens) => tokenManager.setTokens(tokens),
  onTokensRefreshed: (tokens) => tokenManager.setTokens(tokens),
  onTokensRevoked: () => tokenManager.clear(),
});

// After OAuth flow
const tokens = await sdk.exchangeCode(code, state, redirectUri);

// Use token manager
if (!tokenManager.isExpired()) {
  const accessToken = tokenManager.getAccessToken();
  const userInfo = await sdk.getUserInfo(accessToken);
}

Agent Registration

Before using OAuth, register your agent:

const response = await sdk.registerAgent({
  agent_id: "my-ai-agent",
  agent_secret: "secure-random-secret",
  model_name: "gpt-4",
  owner_name: "John Doe",
  owner_email: "[e-mail]",
});

console.log(response.message); // "Agent registered successfully"

Error Handling

All SDK methods throw AuthError objects with detailed information:

import type { AuthError } from "ai-auth";

try {
  const tokens = await sdk.exchangeCode(code, state, redirectUri);
} catch (error) {
  const authError = error as AuthError;
  console.error("Error code:", authError.code);
  console.error("Description:", authError.description);
  console.error("Status:", authError.statusCode);

  // Handle specific errors
  if (authError.code === "token_expired") {
    // Refresh token
  } else if (authError.code === "state_mismatch") {
    // Possible CSRF attack
  }
}

Next Steps

Configuration

Learn about all configuration options

AgentSDK Methods

Explore all available SDK methods

Token Manager

Learn about token management

Utilities

Utility functions for PKCE, JWT parsing, and more