One Auth

https://github.com/withoneai/auth
Admin
One Auth is a drop-in authentication widget that enables users to securely connect their third-party...
Tokens:14,061
Snippets:98
Trust Score:9.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Getting Started with the Skill

Source: https://github.com/withoneai/auth/blob/main/README.md

Guidance on installing the One Auth skill for AI coding agents to assist with setup.

```APIDOC
## Getting Started with the Skill

The easiest way to integrate One Auth is by installing the skill for your AI coding agent. The skill provides step-by-step guidance for setting up the backend token endpoint, frontend component, and connection handling.

```bash
npx skills add withoneai/auth
```

Once installed, your AI coding agent will have full context on how to set up and work with One Auth in your project.
```

--------------------------------

### Install One Auth

Source: https://github.com/withoneai/auth/blob/main/README.md

Instructions for installing the One Auth package using npm or yarn.

```APIDOC
## Install One Auth

With npm:

```bash
npm i @withone/auth
```

With yarn:

```bash
yarn add @withone/auth
```
```

--------------------------------

### Install One Auth Skill for AI Agent

Source: https://github.com/withoneai/auth/blob/main/README.md

Install the One Auth skill for your AI coding agent to get step-by-step guidance on setup.

```bash
npx skills add withoneai/auth
```

--------------------------------

### Install One Auth library

Source: https://context7.com/withoneai/auth/llms.txt

Use npm or yarn to add the @withone/auth package to your project.

```bash
npm install @withone/auth
# or
yarn add @withone/auth
```

--------------------------------

### Install One Auth with npm

Source: https://github.com/withoneai/auth/blob/main/README.md

Use this command to add the One Auth package to your project using npm.

```bash
npm i @withone/auth
```

--------------------------------

### Install One Auth with yarn

Source: https://github.com/withoneai/auth/blob/main/README.md

Use this command to add the One Auth package to your project using yarn.

```bash
yarn add @withone/auth
```

--------------------------------

### GET /v1/available-connectors

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Retrieves a list of all available connectors configured for the project.

```APIDOC
## GET /v1/available-connectors

### Description
Retrieves a list of all available connectors for the current project.

### Method
GET

### Endpoint
/v1/available-connectors

### Parameters
#### Query Parameters
- **authkit** (boolean) - Required - Set to true to filter for AuthKit connectors.
```

--------------------------------

### GET /v1/available-connectors

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Retrieves a list of all available integrations supported by the One API.

```APIDOC
## GET https://api.withone.ai/v1/available-connectors

### Description
Fetches the list of available integrations that can be used for authentication.

### Method
GET

### Endpoint
https://api.withone.ai/v1/available-connectors

### Query Parameters
- **authkit** (boolean) - Required - Set to true
- **limit** (number) - Optional - Limit the number of results

### Response
#### Success Response (200)
- **rows** (array) - List of available connectors
- **total** (number) - Total count of connectors
- **pages** (number) - Total pages
- **page** (number) - Current page

#### Response Example
{
  "rows": [
    {
      "platform": "gmail",
      "name": "Gmail",
      "category": "Communication",
      "image": "https://...",
      "description": "..."
    }
  ],
  "total": 200,
  "pages": 1,
  "page": 1
}
```

--------------------------------

### Example cURL Request for Token Generation

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

This cURL command demonstrates how to make a POST request to the token generation endpoint. Ensure you replace 'https://your-domain.com/api/one-auth' with your actual domain and include the required 'x-user-id' header.

```bash
curl -X POST "https://your-domain.com/api/one-auth" \
  -H "Content-Type: application/json" \
  -H "x-user-id: f47ac10b-58cc-4372-a567-0e02b2c3d479"
```

--------------------------------

### Frontend Integration with React Hook

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Example of how to use the `useOneAuth` hook from `@withone/auth` to open the OneAI Auth widget and handle connection events.

```APIDOC
## Frontend Integration using React Hook

### Description
This section demonstrates how to integrate the OneAI Auth widget into a React application using the provided `useOneAuth` hook. It covers configuration, event handling, and important notes on URL specification.

### `useOneAuth` Hook Configuration

```typescript
import { useOneAuth } from "@withone/auth";

function ConnectButton() {
  const { open } = useOneAuth({
    token: {
      url: "https://your-domain.com/api/one-auth", // MUST be full URL
      headers: {
        "x-user-id": currentUserId,
      },
    },
    selectedConnection: "Gmail",  // Optional: skip list, go directly to this integration
    onSuccess: (connection) => {
      // connection.key - unique identifier for this connection
      // connection.platform - e.g., "gmail"
      // connection.environment - "live" or "test"

      saveConnectionToDatabase(connection);
    },
    onError: (error) => {
      console.error("Connection failed:", error);
    },
    onClose: () => {
      console.log("Modal closed");
    },
  });

  return (
    <button onClick={() => open()}>
      Connect Integration
    </button>
  );
}
```

### Parameters for `useOneAuth`

- **token** (object) - Required - Configuration for the token endpoint.
  - **url** (string) - Required - The full URL of your token generation endpoint (e.g., `https://your-domain.com/api/one-auth`). Relative paths are not supported.
  - **headers** (object) - Optional - Custom headers to send with the token request. Must include `x-user-id`.

- **selectedConnection** (string) - Optional - If provided, the widget will bypass the integration list and go directly to this integration.

- **onSuccess** (function) - Optional - Callback function executed when a connection is successfully established. Receives a `connection` object with `key`, `platform`, and `environment`.

- **onError** (function) - Optional - Callback function executed if an error occurs during the connection process.

- **onClose** (function) - Optional - Callback function executed when the modal is closed by the user.

### Critical Note: Token URL Must Be Full URL

> ⚠️ **Must be a full URL** — relative paths like `/api/one-auth` won't work because the Auth widget runs in an iframe on a different domain. Use the complete URL (e.g., `https://your-domain.com/api/one-auth`).

```typescript
// CORRECT - Full URL
url: "https://your-domain.com/api/one-auth"
url: `${window.location.origin}/api/one-auth`

// INCORRECT - Will fail silently
url: "/api/one-auth"
```
```

--------------------------------

### Using the Auth Component

Source: https://github.com/withoneai/auth/blob/main/README.md

Example of how to use the `useOneAuth` hook in a React component to open the authentication modal.

```APIDOC
## Using the Auth component

Replace the `token URL` with your backend token endpoint URL.

> ⚠️ **Must be a full URL** — relative paths like `/api/one-auth` won't work because the Auth widget runs in an iframe on a different domain. Use the complete URL (e.g., `https://your-domain.com/api/one-auth`).

```tsx
"use client";

import { useOneAuth } from "@withone/auth";

const USER_ID = "your-user-uuid";

export function ConnectIntegrationButton() {
  const { open } = useOneAuth({
    token: {
      url: "https://your-domain.com/api/one-auth",
      headers: {
        "x-user-id": USER_ID,
      },
    },
    onSuccess: (connection) => {
      console.log("Connection created:", connection);
    },
    onError: (error) => {
      console.error("Connection failed:", error);
    },
    onClose: () => {
      console.log("Auth modal closed");
    },
  });

  return <button onClick={open}>Connect Integration</button>;
}
```
```

--------------------------------

### Example: Send Gmail Message via Passthrough API

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Demonstrates how to send an email using the Gmail API through the One passthrough endpoint. Ensure you provide the correct `x-one-connection-key`.

```typescript
const response = await fetch(
  "https://api.withone.ai/v1/passthrough/gmail/messages/send",
  {
    method: "POST",
    headers: {
      "x-one-secret": ONE_SECRET_KEY,
      "x-one-connection-key": user.gmailConnectionKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: "recipient@example.com",
      subject: "Hello",
      body: "Message content",
    }),
  }
);
```

--------------------------------

### API Request to Fetch Available Integrations

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Use this GET request to retrieve a list of available integrations from the One API. Include your secret key in the headers.

```http
GET https://api.withone.ai/v1/available-connectors?authkit=true&limit=300
Headers:
  x-one-secret: YOUR_ONE_SECRET_KEY
```

--------------------------------

### GET /v1/vault/connections

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Lists all connections associated with a specific identity.

```APIDOC
## GET /v1/vault/connections

### Description
Lists all connections associated with a specific identity.

### Method
GET

### Endpoint
/v1/vault/connections

### Parameters
#### Query Parameters
- **identity** (string) - Required - The unique identifier for the user.
- **identityType** (string) - Required - The type of identity, e.g., 'user'.
```

--------------------------------

### List Available Integrations via cURL

Source: https://context7.com/withoneai/auth/llms.txt

Retrieve a list of all available connectors from the One API for display or reference.

```bash
# Get all available connectors
curl -X GET "https://api.withone.ai/v1/available-connectors?authkit=true&limit=300" \
  -H "X-One-Secret: sk_test_your_secret_key_here"

# Response (200 OK):
# {
#   "rows": [
#     {
#       "platform": "gmail",
#       "name": "Gmail",
#       "category": "Communication",
#       "image": "https://assets.withone.ai/connectors/gmail.svg",
#       "description": "Gmail is a free email service..."
#     },
#     {
#       "platform": "slack",
#       "name": "Slack",
#       "category": "Communication",
#       "image": "https://assets.withone.ai/connectors/slack.svg",
#       "description": "Slack is a messaging platform..."
#     }
#   ],
#   "total": 250,
#   "pages": 1,
#   "page": 1
# }
```

--------------------------------

### List Available Integrations

Source: https://context7.com/withoneai/auth/llms.txt

Fetch all available integrations from the One API to display in your own UI or for reference.

```APIDOC
## GET https://api.withone.ai/v1/available-connectors

### Description
Fetches a list of all available integrations (connectors) from the One API. This endpoint can be used to populate UIs or for reference purposes. It accepts query parameters to filter results.

### Method
GET

### Endpoint
https://api.withone.ai/v1/available-connectors

### Parameters
#### Query Parameters
- **authkit** (boolean) - Optional - If set to `true`, filters for connectors compatible with the auth kit.
- **limit** (integer) - Optional - The maximum number of items to return.

#### Request Headers
- **X-One-Secret** (string) - Required - Your secret key for authentication.

### Request Example
```bash
curl -X GET "https://api.withone.ai/v1/available-connectors?authkit=true&limit=300" \
  -H "X-One-Secret: sk_test_your_secret_key_here"
```

### Response
#### Success Response (200)
- **rows** (array) - A list of available connector objects.
- **total** (integer) - The total number of available connectors.
- **pages** (integer) - The total number of pages.
- **page** (integer) - The current page number.

#### Response Example
```json
{
  "rows": [
    {
      "platform": "gmail",
      "name": "Gmail",
      "category": "Communication",
      "image": "https://assets.withone.ai/connectors/gmail.svg",
      "description": "Gmail is a free email service..."
    },
    {
      "platform": "slack",
      "name": "Slack",
      "category": "Communication",
      "image": "https://assets.withone.ai/connectors/slack.svg",
      "description": "Slack is a messaging platform..."
    }
  ],
  "total": 250,
  "pages": 1,
  "page": 1
}
```
```

--------------------------------

### Initialize and Open One Auth Widget

Source: https://github.com/withoneai/auth/blob/main/README.md

Use the useOneAuth hook to initialize the Auth widget and open it. Ensure the token URL is a full URL, as relative paths are not supported due to the widget running in an iframe.

```tsx
"use client";

import { useOneAuth } from "@withone/auth";

const USER_ID = "your-user-uuid";

export function ConnectIntegrationButton() {
  const { open } = useOneAuth({
    token: {
      url: "https://your-domain.com/api/one-auth",
      headers: {
        "x-user-id": USER_ID,
      },
    },
    onSuccess: (connection) => {
      console.log("Connection created:", connection);
    },
    onError: (error) => {
      console.error("Connection failed:", error);
    },
    onClose: () => {
      console.log("Auth modal closed");
    },
  });

  return <button onClick={open}>Connect Integration</button>;
}
```

--------------------------------

### Configuration Options

Source: https://github.com/withoneai/auth/blob/main/README.md

Details on the available configuration options for the `useOneAuth` hook.

```APIDOC
### Configuration Options

| Option | Type | Description |
|---|---|---|
| `token.url` | `string` | Full URL of your backend token endpoint |
| `token.headers` | `object` | Headers to send with the token request (e.g., user ID) |
| `selectedConnection` | `string` | Pre-select an integration by display name (e.g., `"Gmail"`) |
| `appTheme` | `"dark" | "light"` | Theme for the Auth modal |
| `title` | `string` | Custom title for the modal |
| `imageUrl` | `string` | Custom logo URL to display in the modal |
| `companyName` | `string` | Your company name to display in the modal |
| `onSuccess` | `(connection) => void` | Callback when a connection is successfully created |
| `onError` | `(error) => void` | Callback when the connection fails |
| `onClose` | `() => void` | Callback when the modal is closed |
```

--------------------------------

### Backend Token Generation

Source: https://github.com/withoneai/auth/blob/main/README.md

Information on setting up a backend endpoint to generate session tokens for One Auth.

```APIDOC
## Backend Token Generation

To enable Auth connections, your backend needs an endpoint that generates a session token by calling the One API.

### Environment Variables

```env
ONE_SECRET_KEY=sk_test_your_secret_key_here
```

| Variable | Description |
|---|---|
| `ONE_SECRET_KEY` | Your secret key from the [One dashboard](https://app.withone.ai/settings/api-keys) |
```

--------------------------------

### POST /v1/passthrough/{platform}/{action}

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Executes a platform-specific action via the passthrough endpoint.

```APIDOC
## POST /v1/passthrough/{platform}/{action}

### Description
Executes a platform-specific action via the passthrough endpoint.

### Method
POST

### Endpoint
/v1/passthrough/{platform}/{action}

### Parameters
#### Path Parameters
- **platform** (string) - Required - The target platform (e.g., 'gmail').
- **action** (string) - Required - The specific action to perform.
```

--------------------------------

### POST /v1/passthrough/{platform}/{action}

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Executes an API call to a third-party platform using a stored connection key.

```APIDOC
## POST https://api.withone.ai/v1/passthrough/{platform}/{action}

### Description
Performs an authenticated request to a third-party service via the WithOne passthrough proxy.

### Method
POST

### Endpoint
https://api.withone.ai/v1/passthrough/{platform}/{action}

### Parameters
#### Path Parameters
- **platform** (string) - Required - The platform identifier (e.g., gmail)
- **action** (string) - Required - The specific API action to perform

### Request Example
{
  "to": "recipient@example.com",
  "subject": "Hello",
  "body": "Message content"
}
```

--------------------------------

### Recommended Database Schema for User Connections

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

A SQL schema for storing user connection details. Ensure `connection_key` is unique to prevent duplicate connections for the same user and platform.

```sql
CREATE TABLE user_connections (
    id UUID PRIMARY KEY,
    user_id TEXT NOT NULL,
    platform TEXT NOT NULL,
    connection_key TEXT UNIQUE,
    environment TEXT DEFAULT 'live',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

--------------------------------

### Persist User Connections

Source: https://context7.com/withoneai/auth/llms.txt

Recommended database schema and implementation for saving connection details returned by the onSuccess callback.

```sql
-- PostgreSQL schema for storing user connections
CREATE TABLE user_connections (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id TEXT NOT NULL,
    platform TEXT NOT NULL,
    connection_key TEXT UNIQUE NOT NULL,
    environment TEXT DEFAULT 'live',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Index for fast lookups by user
CREATE INDEX idx_user_connections_user_id ON user_connections(user_id);

-- Index for lookups by platform
CREATE INDEX idx_user_connections_platform ON user_connections(platform);
```

```typescript
// Example: Save connection on success
const { open } = useOneAuth({
  token: { url: "https://your-domain.com/api/one-auth", headers: { "x-user-id": userId } },
  onSuccess: async (connection) => {
    await fetch("/api/connections", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        user_id: userId,
        platform: connection.platform,
        connection_key: connection.key,
        environment: connection.environment,
      }),
    });
    refreshConnectionsList();
  },
});
```

--------------------------------

### Initialize AuthKit Frontend Hook

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Use the `useOneAuth` hook in your frontend application to manage authentication flows. Pass configuration options like token, success/error callbacks, and selected connection.

```typescript
import { useOneAuth } from "@withone/auth";
const { open, close } = useOneAuth({ token, onSuccess, onError, onClose, selectedConnection });
```

--------------------------------

### Configure Direct Integration Authentication

Source: https://context7.com/withoneai/auth/llms.txt

Use the selectedConnection parameter to bypass the integration list and launch directly into a specific provider's authentication flow.

```typescript
import { useOneAuth } from "@withone/auth";

function ConnectGmailButton() {
  const { open } = useOneAuth({
    token: {
      url: "https://your-domain.com/api/one-auth",
      headers: { "x-user-id": "user-uuid-123" },
    },
    selectedConnection: "Gmail", // Opens directly to Gmail auth flow
    onSuccess: (connection) => {
      console.log("Gmail connected:", connection.key);
    },
    onError: (error) => {
      console.error("Gmail connection failed:", error);
    },
  });

  return <button onClick={() => open()}>Connect Gmail</button>;
}
```

--------------------------------

### Pre-select Integration Flow

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Pass the integration's display name to bypass the integration list and directly open a specific authentication flow. Use `undefined` to show the integration list.

```typescript
// Opens directly to Gmail auth flow
selectedConnection: "Gmail"
```

```typescript
// Opens directly to Slack auth flow
selectedConnection: "Slack"
```

```typescript
// Opens to integration list (user picks)
selectedConnection: undefined
```

--------------------------------

### Success Response JSON Structure

Source: https://github.com/withoneai/auth/blob/main/README.md

The expected JSON response format containing the paginated list of integrations.

```json
{
  "rows": [
    {
      "id": 41596,
      "connectionDefId": 34,
      "type": "api",
      "title": "ActiveCampaign",
      "image": "https://assets.withone.ai/connectors/activecampaign.svg",
      "environment": "test",
      "tags": [],
      "active": true
    },
    {
      "id": 41524,
      "connectionDefId": 109,
      "type": "api",
      "title": "Anthropic",
      "image": "https://assets.withone.ai/connectors/anthropic.svg",
      "environment": "test",
      "tags": [],
      "active": true
    }
  ],
  "total": 247,
  "pages": 3,
  "page": 1,
  "requestId": 110256
}
```

--------------------------------

### Retrieve User Connections

Source: https://context7.com/withoneai/auth/llms.txt

Fetch all connections associated with a specific user identity using the One API.

```bash
# Get all connections for a user
curl -X GET "https://api.withone.ai/v1/vault/connections?identity=user-uuid-123&identityType=user" \
  -H "X-One-Secret: sk_test_your_secret_key_here"
```

--------------------------------

### Configure useOneAuth options

Source: https://context7.com/withoneai/auth/llms.txt

Define the configuration object for the useOneAuth hook to customize UI and behavior.

```typescript
interface EventLinkProps {
  // Required: Token endpoint configuration
  token: {
    url: string;                        // Full URL to your backend token endpoint
    headers?: Record<string, unknown>;  // Custom headers (e.g., user identification)
  };

  // Optional: UI customization
  baseUrl?: string;          // Custom Auth UI URL (default: https://auth.withone.ai)
  appTheme?: "dark" | "light";
  title?: string;            // Modal title
  imageUrl?: string;         // Company logo URL
  companyName?: string;      // Company name displayed in modal

  // Optional: Behavior
  selectedConnection?: string; // Pre-select integration by display name (e.g., "Gmail")
  showNameInput?: boolean;     // Show name input field for the connection

  // Optional: Callbacks
  onSuccess?: (connection: ConnectionRecord) => void;
  onError?: (error: string) => void;
  onClose?: () => void;
}
```

--------------------------------

### Auth Sequence Diagram

Source: https://github.com/withoneai/auth/blob/main/README.md

Visual representation of the authentication flow between the user, application, backend, and One Auth service.

```mermaid
sequenceDiagram
    participant User
    participant YourApp as Your Application
    participant YourBackend as Your Backend
    participant One as One Auth
    participant Integration as Third-party Integration

    User->>YourApp: Clicks "Connect Integration"
    YourApp->>One: Open Auth modal
    One->>YourBackend: Request Auth token (page=1&limit=100)
    YourBackend->>One: Generate token with user identity
    One->>One: Display integrations list
    User->>One: Select integration & authenticate
    One->>Integration: OAuth handshake
    Integration->>One: Access token
    One->>One: Store encrypted credentials
    One->>YourApp: Return connection details
    YourApp->>User: Connection successful!
```

--------------------------------

### Implement Next.js Token Endpoint

Source: https://context7.com/withoneai/auth/llms.txt

Create a secure API route to generate One Auth session tokens. Ensure the endpoint handles CORS and validates the user identity via headers.

```typescript
// Next.js API Route: app/api/one-auth/route.ts
import { NextRequest, NextResponse } from "next/server";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "POST, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization, x-user-id",
};

export async function OPTIONS() {
  return NextResponse.json({}, { headers: corsHeaders });
}

export async function POST(req: NextRequest) {
  try {
    const userId = req.headers.get("x-user-id");
    if (!userId) {
      return NextResponse.json(
        { error: "Unauthorized" },
        { status: 401, headers: corsHeaders }
      );
    }

    // Auth widget sends pagination params as query parameters
    const page = req.nextUrl.searchParams.get("page");
    const limit = req.nextUrl.searchParams.get("limit");

    const response = await fetch(
      `https://api.withone.ai/v1/authkit/token?page=${page}&limit=${limit}`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-One-Secret": process.env.ONE_SECRET_KEY!,
        },
        body: JSON.stringify({
          identity: userId,
          identityType: "user", // "user" | "team" | "organization" | "project"
        }),
      }
    );

    if (!response.ok) {
      return NextResponse.json(
        { error: "Failed to generate token" },
        { status: response.status, headers: corsHeaders }
      );
    }

    const data = await response.json();
    return NextResponse.json(data, { headers: corsHeaders });
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to generate token" },
      { status: 500, headers: corsHeaders }
    );
  }
}
```

--------------------------------

### Generate Auth Token via cURL

Source: https://context7.com/withoneai/auth/llms.txt

Use the One API to generate authentication tokens by providing the user's identity and secret key.

```bash
# Generate auth token for a user
curl -X POST "https://api.withone.ai/v1/authkit/token?page=1&limit=100" \
  -H "Content-Type: application/json" \
  -H "X-One-Secret: sk_test_your_secret_key_here" \
  -d '{
    "identity": "user-uuid-123",
    "identityType": "user"
  }'

# Response (200 OK):
# {
#   "rows": [
#     {
#       "id": 41596,
#       "connectionDefId": 34,
#       "type": "api",
#       "title": "ActiveCampaign",
#       "image": "https://assets.withone.ai/connectors/activecampaign.svg",
#       "environment": "test",
#       "tags": [],
#       "active": true
#     },
#     {
#       "id": 41524,
#       "connectionDefId": 109,
#       "type": "api",
#       "title": "Anthropic",
#       "image": "https://assets.withone.ai/connectors/anthropic.svg",
#       "environment": "test",
#       "tags": [],
#       "active": true
#     }
#   ],
#   "total": 247,
#   "pages": 3,
#   "page": 1,
#   "requestId": 110256
# }
```

--------------------------------

### Available Integrations Response Structure

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

The JSON response structure for available integrations, including platform details, names, categories, and image URLs.

```json
{
  "rows": [
    {
      "platform": "gmail",
      "name": "Gmail",
      "category": "Communication",
      "image": "https://...",
      "description": "..."
    }
  ],
  "total": 200,
  "pages": 1,
  "page": 1
}
```

--------------------------------

### Implement Next.js API Route for Auth

Source: https://github.com/withoneai/auth/blob/main/README.md

Handles the POST request from the Auth widget, extracts user identity, and proxies the request to the One Auth API.

```typescript
import { NextRequest, NextResponse } from "next/server";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "POST, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization, x-user-id",
};

export async function OPTIONS() {
  return NextResponse.json({}, { headers: corsHeaders });
}

export async function POST(req: NextRequest) {
  try {
    const userId = req.headers.get("x-user-id");

    if (!userId) {
      return NextResponse.json(
        { error: "Unauthorized" },
        { status: 401, headers: corsHeaders }
      );
    }

    // The Auth widget sends pagination params as query parameters
    const page = req.nextUrl.searchParams.get("page");
    const limit = req.nextUrl.searchParams.get("limit");

    const response = await fetch(
      `https://api.withone.ai/v1/authkit/token?page=${page}&limit=${limit}`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-One-Secret": process.env.ONE_SECRET_KEY!,
        },
        body: JSON.stringify({
          identity: userId,
          identityType: "user", // "user" | "team" | "organization" | "project"
        }),
      }
    );

    if (!response.ok) {
      return NextResponse.json(
        { error: "Failed to generate token" },
        { status: response.status, headers: corsHeaders }
      );
    }

    const token = await response.json();
    return NextResponse.json(token, { headers: corsHeaders });
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to generate token" },
      { status: 500, headers: corsHeaders }
    );
  }
}
```

--------------------------------

### Generate Auth Token API Endpoint (TypeScript)

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

This Next.js API route handles POST requests to generate authentication tokens. It requires an 'x-user-id' header and fetches a token from the WithOne AI API. Ensure the ONE_SECRET_KEY environment variable is set.

```typescript
import { NextRequest, NextResponse } from "next/server";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "POST, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization, x-user-id",
};

export async function OPTIONS() {
  return NextResponse.json({}, { headers: corsHeaders });
}

// POST /api/one-auth
export async function POST(req: NextRequest) {
  try {
    const userId = req.headers.get("x-user-id");
    if (!userId) {
      return NextResponse.json(
        { error: "Unauthorized" },
        { status: 401, headers: corsHeaders }
      );
    }

    // The Auth widget sends pagination params as query parameters
    const page = req.nextUrl.searchParams.get("page");
    const limit = req.nextUrl.searchParams.get("limit");

    const response = await fetch(
      `https://api.withone.ai/v1/authkit/token?page=${page}&limit=${limit}`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-One-Secret": process.env.ONE_SECRET_KEY!,
        },
        body: JSON.stringify({
          identity: userId,
          identityType: "user",
        }),
      }
    );

    if (!response.ok) {
      return NextResponse.json(
        { error: "Failed to generate token" },
        { status: response.status, headers: corsHeaders }
      );
    }

    const data = await response.json();
    return NextResponse.json(data, { headers: corsHeaders });
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to generate token" },
      { status: 500, headers: corsHeaders }
    );
  }
}
```

--------------------------------

### One Auth Environment Variable

Source: https://github.com/withoneai/auth/blob/main/README.md

Set the ONE_SECRET_KEY environment variable with your secret key from the One dashboard to enable Auth connections.

```env
ONE_SECRET_KEY=sk_test_your_secret_key_here
```

--------------------------------

### Save Connection on Success Callback

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Implement the `onSuccess` callback to save the authenticated connection details to your database. This function is called after a successful authentication flow.

```typescript
onSuccess: async (connection) => {
  await fetch("/api/connections", {
    method: "POST",
    body: JSON.stringify({
      user_id: currentUserId,
      platform: connection.platform,
      connection_key: connection.key,
      environment: connection.environment,
    }),
  });

  refreshConnectionsList();
}
```

--------------------------------

### Backend Token Endpoint

Source: https://context7.com/withoneai/auth/llms.txt

Your backend must provide a token endpoint that generates One Auth session tokens. The endpoint must be accessible via full URL with proper CORS headers.

```APIDOC
## POST /api/one-auth

### Description
This endpoint generates One Auth session tokens for a given user identity. It requires a `x-user-id` header for authentication and accepts `page` and `limit` as query parameters for potential pagination of associated data.

### Method
POST

### Endpoint
/api/one-auth

### Parameters
#### Request Headers
- **x-user-id** (string) - Required - The ID of the user for whom the token is being generated.

#### Query Parameters
- **page** (string) - Optional - The page number for pagination.
- **limit** (string) - Optional - The number of items per page for pagination.

### Request Body
This endpoint does not explicitly define a request body in the provided example, but the underlying `fetch` call to `https://api.withone.ai/v1/authkit/token` uses a JSON body.

### Request Example (Next.js)
```typescript
// Next.js API Route: app/api/one-auth/route.ts
import { NextRequest, NextResponse } from "next/server";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "POST, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization, x-user-id",
};

export async function OPTIONS() {
  return NextResponse.json({}, { headers: corsHeaders });
}

export async function POST(req: NextRequest) {
  try {
    const userId = req.headers.get("x-user-id");
    if (!userId) {
      return NextResponse.json(
        { error: "Unauthorized" },
        { status: 401, headers: corsHeaders }
      );
    }

    // Auth widget sends pagination params as query parameters
    const page = req.nextUrl.searchParams.get("page");
    const limit = req.nextUrl.searchParams.get("limit");

    const response = await fetch(
      `https://api.withone.ai/v1/authkit/token?page=${page}&limit=${limit}`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-One-Secret": process.env.ONE_SECRET_KEY!,
        },
        body: JSON.stringify({
          identity: userId,
          identityType: "user", // "user" | "team" | "organization" | "project"
        }),
      }
    );

    if (!response.ok) {
      return NextResponse.json(
        { error: "Failed to generate token" },
        { status: response.status, headers: corsHeaders }
      );
    }

    const data = await response.json();
    return NextResponse.json(data, { headers: corsHeaders });
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to generate token" },
      { status: 500, headers: corsHeaders }
    );
  }
}
```

### Response
#### Success Response (200)
- **rows** (array) - A list of associated connection objects.
- **total** (integer) - The total number of available connections.
- **pages** (integer) - The total number of pages.
- **page** (integer) - The current page number.
- **requestId** (integer) - A unique identifier for the request.

#### Response Example
```json
{
  "rows": [
    {
      "id": 41596,
      "connectionDefId": 34,
      "type": "api",
      "title": "ActiveCampaign",
      "image": "https://assets.withone.ai/connectors/activecampaign.svg",
      "environment": "test",
      "tags": [],
      "active": true
    },
    {
      "id": 41524,
      "connectionDefId": 109,
      "type": "api",
      "title": "Anthropic",
      "image": "https://assets.withone.ai/connectors/anthropic.svg",
      "environment": "test",
      "tags": [],
      "active": true
    }
  ],
  "total": 247,
  "pages": 3,
  "page": 1,
  "requestId": 110256
}
```
```

--------------------------------

### POST /api/one-auth

Source: https://github.com/withoneai/auth/blob/main/README.md

This endpoint is responsible for generating authentication tokens. It extracts user identity from headers and handles pagination parameters to interact with the OneAI AuthKit.

```APIDOC
## POST /api/one-auth

### Description
This endpoint generates authentication tokens by extracting user identity from headers and utilizing pagination parameters to communicate with the OneAI AuthKit.

### Method
POST

### Endpoint
/api/one-auth

### Parameters
#### Request Headers
- **x-user-id** (string) - Required - Unique identifier for the user (e.g., UUID from your auth system)

#### Query Parameters
- **page** (integer) - Optional - Current page number for paginated integration list
- **limit** (integer) - Optional - Number of integrations per page

### Request Example
```json
{
  "identity": "user-uuid-12345",
  "identityType": "user"
}
```

### Response
#### Success Response (200)
- **rows** (array) - A list of available integrations.
- **total** (integer) - The total number of available integrations.
- **pages** (integer) - The total number of pages.
- **page** (integer) - The current page number.
- **requestId** (integer) - The ID of the request.

#### Response Example
```json
{
  "rows": [
    {
      "id": 41596,
      "connectionDefId": 34,
      "type": "api",
      "title": "ActiveCampaign",
      "image": "https://assets.withone.ai/connectors/activecampaign.svg",
      "environment": "test",
      "tags": [],
      "active": true
    },
    {
      "id": 41524,
      "connectionDefId": 109,
      "type": "api",
      "title": "Anthropic",
      "image": "https://assets.withone.ai/connectors/anthropic.svg",
      "environment": "test",
      "tags": [],
      "active": true
    }
  ],
  "total": 247,
  "pages": 3,
  "page": 1,
  "requestId": 110256
}
```
```

--------------------------------

### One API Token Generation

Source: https://context7.com/withoneai/auth/llms.txt

Generate authentication tokens by calling the One API from your backend with the user's identity.

```APIDOC
## POST https://api.withone.ai/v1/authkit/token

### Description
This endpoint generates authentication tokens by calling the One API from your backend with the user's identity. It requires an `X-One-Secret` header and accepts `page` and `limit` as query parameters.

### Method
POST

### Endpoint
https://api.withone.ai/v1/authkit/token

### Parameters
#### Query Parameters
- **page** (string) - Optional - The page number for pagination.
- **limit** (string) - Optional - The number of items per page for pagination.

#### Request Headers
- **Content-Type** (string) - Required - `application/json`
- **X-One-Secret** (string) - Required - Your secret key for authentication.

#### Request Body
- **identity** (string) - Required - The identity of the user, team, organization, or project.
- **identityType** (string) - Required - The type of identity. Possible values: `user`, `team`, `organization`, `project`.

### Request Example
```bash
curl -X POST "https://api.withone.ai/v1/authkit/token?page=1&limit=100" \
  -H "Content-Type: application/json" \
  -H "X-One-Secret: sk_test_your_secret_key_here" \
  -d '{
    "identity": "user-uuid-123",
    "identityType": "user"
  }'
```

### Response
#### Success Response (200)
- **rows** (array) - A list of associated connection objects.
- **total** (integer) - The total number of available connections.
- **pages** (integer) - The total number of pages.
- **page** (integer) - The current page number.
- **requestId** (integer) - A unique identifier for the request.

#### Response Example
```json
{
  "rows": [
    {
      "id": 41596,
      "connectionDefId": 34,
      "type": "api",
      "title": "ActiveCampaign",
      "image": "https://assets.withone.ai/connectors/activecampaign.svg",
      "environment": "test",
      "tags": [],
      "active": true
    },
    {
      "id": 41524,
      "connectionDefId": 109,
      "type": "api",
      "title": "Anthropic",
      "image": "https://assets.withone.ai/connectors/anthropic.svg",
      "environment": "test",
      "tags": [],
      "active": true
    }
  ],
  "total": 247,
  "pages": 3,
  "page": 1,
  "requestId": 110256
}
```
```

--------------------------------

### Auth Hook Configuration Options

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Interface defining the configuration options for the OneAuth hook, including token URLs, UI customization, and event callbacks.

```typescript
interface AuthProps {
  token: {
    url: string;                        // Full URL to your token endpoint
    headers?: Record<string, unknown>;  // Custom headers for token request
  };
  baseUrl?: string;          // Custom Auth UI URL (default: https://auth.withone.ai)
  appTheme?: "dark" | "light";
  title?: string;            // Modal title
  imageUrl?: string;         // Company logo URL
  companyName?: string;      // Company name displayed in modal
  selectedConnection?: string; // Pre-select an integration by display name
  showNameInput?: boolean;   // Show name input for the connection
  onSuccess?: (connection: ConnectionRecord) => void;
  onError?: (error: string) => void;
  onClose?: () => void;
}
```

--------------------------------

### POST /api/connections

Source: https://github.com/withoneai/auth/blob/main/skills/one-auth/SKILL.md

Saves a new connection record to the database after a successful authentication flow.

```APIDOC
## POST /api/connections

### Description
Saves the connection details returned by the authentication flow to the application database.

### Method
POST

### Endpoint
/api/connections

### Request Body
- **user_id** (string) - Required - The ID of the user
- **platform** (string) - Required - The platform identifier (e.g., gmail)
- **connection_key** (string) - Required - The unique key for the connection
- **environment** (string) - Required - The environment (e.g., live or test)

### Request Example
{
  "user_id": "currentUserId",
  "platform": "gmail",
  "connection_key": "connection.key",
  "environment": "live"
}
```

--------------------------------

### Integrate useOneAuth hook

Source: https://context7.com/withoneai/auth/llms.txt

The useOneAuth hook provides open and close functions to manage the authentication modal. Ensure the token URL is a full absolute URL.

```typescript
import { useOneAuth } from "@withone/auth";

function ConnectIntegrationButton() {
  const { open, close } = useOneAuth({
    token: {
      url: "https://your-domain.com/api/one-auth", // Must be full URL, not relative
      headers: {
        "x-user-id": "user-uuid-123",
      },
    },
    appTheme: "light", // or "dark"
    title: "Connect Your Apps",
    companyName: "My Company",
    imageUrl: "https://example.com/logo.png",
    selectedConnection: "Gmail", // Optional: skip list and go directly to this integration
    showNameInput: true,
    onSuccess: (connection) => {
      // connection.key - unique identifier for API calls
      // connection.platform - e.g., "gmail", "slack"
      // connection.environment - "live" or "test"
      console.log("Connected:", connection.platform);
      saveToDatabase({
        userId: "user-uuid-123",
        connectionKey: connection.key,
        platform: connection.platform,
      });
    },
    onError: (error) => {
      console.error("Connection failed:", error);
    },
    onClose: () => {
      console.log("Modal closed by user");
    },
  });

  return (
    <div>
      <button onClick={() => open()}>Connect Integration</button>
      <button onClick={() => close()}>Cancel</button>
    </div>
  );
}
```
Tokens:
Raw