Quick Start

Installation

npm install ai-auth

yarn add ai-auth

pnpm add ai-auth

1. Register Your Agent

Before you can authenticate, you need to register your AI agent:

Visit Registration Page

Go to the registration endpoint or use the demo frontend at /register

Fill Registration Form

Provide your agent details: - Agent ID: Unique identifier (e.g., my_agent_123) - Agent Secret: Strong password (min 8 characters) - Model Name: AI model being used (e.g., gpt-4) - Owner Name: Your name - Owner Email: Your email address

Get Your Credentials

Save your agent_id - this becomes your OAuth client_id

The agent_id is your OAuth client ID. Keep your agent_secret secure!

2. React Application Setup

Wrap Your App with AuthProvider

App.tsx

import { AuthProvider } from "ai-auth";
import { BrowserRouter } from "react-router-dom";

function App() {
  return (
    <AuthProvider
      config={{
        clientId: "your_agent_id",
        redirectUri: "http://localhost:3000/callback",
        authServerUrl: "http://localhost:8787",
        scope: "openid profile email",
      }}
    >
      <BrowserRouter>{/* Your app routes */}</BrowserRouter>
    </AuthProvider>
  );
}

import { SignInWithAuthAgent } from "ai-auth";

export function LoginPage() {
  return (
    <div>
      <h1>Login</h1>
      <SignInWithAuthAgent
        clientId="your_agent_id"
        redirectUri="http://localhost:3000/callback"
        authServerUrl="http://localhost:8787"
        width={320}
        height={56}
      />
    </div>
  );
}

Handle the OAuth Callback

Callback.tsx

import { useEffect } from "react";
import { useNavigate } from "react-router-dom";
import { useAuth } from "ai-auth";

export function CallbackPage() {
  const navigate = useNavigate();
  const { isAuthenticated, isLoading, error } = useAuth();

  useEffect(() => {
    if (!isLoading) {
      if (isAuthenticated) {
        navigate("/dashboard");
      } else if (error) {
        navigate("/login");
      }
    }
  }, [isAuthenticated, isLoading, error, navigate]);

  return <div>Completing authentication...</div>;
}

Use Authentication State

Dashboard.tsx

import { useAuth, ProtectedRoute } from "ai-auth";

function DashboardContent() {
  const { user, logout } = useAuth();

  return (
    <div>
      <h1>Welcome, {user?.name}!</h1>
      <p>Agent ID: {user?.agent_id}</p>
      <p>Model: {user?.model_name}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

export function Dashboard() {
  return (
    <ProtectedRoute>
      <DashboardContent />
    </ProtectedRoute>
  );
}

3. Vanilla JavaScript Setup

For non-React applications:

index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Auth-Agent Demo</title>
  </head>
  <body>
    <div id="app"></div>

    <script type="module">
      import { AuthAgentClient } from "ai-auth";

      const client = new AuthAgentClient({
        clientId: "your_agent_id",
        redirectUri: "http://localhost:3000",
        authServerUrl: "http://localhost:8787",
      });

      // Check if handling callback
      if (window.location.search.includes("code=")) {
        const result = await client.handleCallback();
        if (result.success) {
          console.log("Logged in!", result.user);
        }
      } else if (client.isAuthenticated()) {
        const user = await client.getUserInfo();
        console.log("User:", user);
      } else {
        // Show login button
        document.getElementById("app").innerHTML = `
        <button onclick="login()">Sign in with Auth-Agent</button>
      `;
      }

      window.login = () => client.redirectToLogin();
    </script>
  </body>
</html>

4. Test Your Integration

Start Your App

Run your development server

Click Sign In

Click the “Sign in with Auth-Agent” button

Authenticate

Enter your agent credentials on the auth page

Success!

You’ll be redirected back to your app with a valid session

Configuration Options

clientId

string

required

Your agent ID (obtained during registration)

redirectUri

string

required

Where to redirect after authentication

authServerUrl

string

default:"https://api.auth-agent.com"

Auth-Agent server URL

scope

string

default:"openid profile email"

OAuth scopes to request

storage

string

default:"localStorage"

Token storage: localStorage, sessionStorage, or memory

autoRefresh

boolean

default:true

Automatically refresh tokens before expiration

Next Steps

Explore React Hooks

Learn about useAuth, useUser, and more

API Reference

Complete API documentation

Protected Routes

Secure your routes and components

Examples

See complete working examples

Troubleshooting

Client ID is not registered

Make sure you’ve completed agent registration first. Visit /register to create your agent.

redirect_uri mismatch

The redirectUri must exactly match what you registered. Check protocol, domain, port, and path.

PKCE verification failed

Clear localStorage and try again. Make sure cookies are enabled.

Server not responding

Ensure the Auth-Agent server is running and accessible at the configured URL.

Get Started

Core Concepts

Components

Guides

Advanced

Installation

1. Register Your Agent

2. React Application Setup

Wrap Your App with AuthProvider

Handle the OAuth Callback

Use Authentication State

3. Vanilla JavaScript Setup

4. Test Your Integration

Configuration Options

Next Steps

Explore React Hooks

API Reference

Protected Routes

Examples

Troubleshooting

​Installation

​1. Register Your Agent

​2. React Application Setup

​Wrap Your App with AuthProvider

​Add the Sign-In Button

​Handle the OAuth Callback

​Use Authentication State

​3. Vanilla JavaScript Setup

​4. Test Your Integration

​Configuration Options

​Next Steps

Explore React Hooks

API Reference

Protected Routes

Examples

​Troubleshooting

Installation

1. Register Your Agent

2. React Application Setup

Wrap Your App with AuthProvider

Add the Sign-In Button

Handle the OAuth Callback

Use Authentication State

3. Vanilla JavaScript Setup

4. Test Your Integration

Configuration Options

Next Steps

Troubleshooting