Skip to main content

​
Installation

npm install ai-auth

​
1. Register Your Agent

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

Visit Registration Page

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

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
3

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>
  );
}

​
Add the Sign-In Button

Login.tsx
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

1

Start Your App

Run your development server
2

Click Sign In

Click the “Sign in with Auth-Agent” button
3

Authenticate

Enter your agent credentials on the auth page
4

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

Make sure you’ve completed agent registration first. Visit /register to create your agent.
The redirectUri must exactly match what you registered. Check protocol, domain, port, and path.
Clear localStorage and try again. Make sure cookies are enabled.
Ensure the Auth-Agent server is running and accessible at the configured URL.