Documentation

Everything you need to integrate AgentAuth into your application.

Installation

npm install agentauth

Quick Start

import { AgentAuth } from 'agentauth'

const auth = new AgentAuth('your-api-key')

// 1. Generate a connect URL for your user
const url = await auth.getConnectUrl({
  userId: 'user_123',
  service: 'google',
  scopes: ['gmail.send'],
  redirectUrl: 'https://yourapp.com/connected'
})

// 2. Redirect your user to this URL
// They will see Google's consent screen

// 3. After they approve, get their token anytime
const token = await auth.getToken('user_123', 'google')

// 4. Use the token with Google APIs
// Token auto-refreshes. Always valid.

Available Scopes

Scope	Description
`gmail.readonly`	Read emails
`gmail.send`	Send emails
`gmail.full`	Full Gmail access
`calendar.readonly`	Read calendar events
`calendar.write`	Read and write calendar events
`drive.readonly`	Read Drive files
`drive.file`	Read and write Drive files

API Reference

`auth.getConnectUrl(options)`

Generates a URL for users to connect their Google account.

Options:

userId (required): Your internal user ID
service (required): 'google'
scopes (optional): Array of scopes. Default: ['gmail.readonly']
redirectUrl (optional): Where to redirect after connection

Returns:

Promise<string> - The OAuth URL

`auth.getToken(userId, service)`

Gets a valid access token for a user. Automatically refreshes if expired.

Parameters:

userId (required): Your internal user ID
service (optional): 'google' (default)

Returns:

Promise<string> - A valid access token

`auth.isConnected(userId, service)`

Checks if a user has connected their account.

Returns:

Promise<boolean>

Error Handling

import { AgentAuth } from 'agentauth'

const auth = new AgentAuth('your-api-key')

try {
  const token = await auth.getToken('user_123', 'google')
  // Use token with Google APIs
} catch (error) {
  if (error.message.includes('not connected')) {
    // User needs to connect their account first
    const url = await auth.getConnectUrl({ 
      userId: 'user_123', 
      service: 'google' 
    })
    // Redirect user to url
  }
}

Need Help?

If you have questions or run into issues, we're here to help.

Email support GitHub