Authentication

Overview

TalkifAI supports two authentication methods:

Session-based authentication — For Studio UI and logged-in users (via Better Auth)
API keys — For server-to-server API access

The authentication method you use depends on your use case:

Use Case	Authentication Method
Studio UI (logged-in users)	Session-based
Marketing site → Studio API	API key (`x-api-key`)
External backend → Studio API	API key (`x-api-key`)
Backend service (your own)	Session-based or API key

Session-Based Authentication

For applications where users log in to TalkifAI Studio, authentication is handled automatically via Better Auth session cookies.

How It Works

User logs in via TalkifAI Studio
Session cookie is set automatically
All API requests include the session cookie
Backend validates session via auth.api.getSession()

Example (Server-Side)

import { auth } from "@/src/lib/auth";
import { headers } from "next/headers";

export async function GET() {
  const session = await auth.api.getSession({
    headers: await headers()
  });

  if (!session?.user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // User is authenticated
  console.log("User:", session.user.email);
  console.log("Organization:", session.session.activeOrganizationId);
}

Example (Client-Side)

import { authClient } from "@/src/lib/auth-client";

function MyComponent() {
  const { data: session } = authClient.useSession();

  if (!session) {
    return <div>Please log in</div>;
  }

  return (
    <div>
      <p>Welcome, {session.user.name}!</p>
      <p>Organization: {session.session.activeOrganizationId}</p>
    </div>
  );
}

API Key Authentication

For server-to-server communication (e.g., marketing site → Studio API, external backends), use API keys.

Generating an API Key (Via Studio UI)

Navigation: Studio → Organization → API Keys URL: /organization/api-key

Owner access required: Only organization owners can generate API keys. Admins and Members cannot access this feature.

Step-by-Step Process:

Navigate to API Keys Page
- Go to Studio → Organization (sidebar)
- Click API Keys in the organization settings
Enter Key Details
- Key Name (required, max 50 characters)
  - Example: “Production Server”, “Marketing Site”, “Dev Testing”
- Organization is automatically selected from your active session
Click “Generate API Key”
- Button shows loading spinner while processing
- Backend creates key via Better Auth
Copy the Key Immediately ⚠️
- The full key is shown only once in a dark gray box
- Click Copy button to copy to clipboard
- Shows “Copied!” confirmation for 2 seconds
- Important: You cannot view the key again after leaving the page
Key Details Shown
- Created date
- Expires date (1 year from creation)
- API endpoints that accept this key:
  - Public Chat API: https://api.talkifai.dev/v1/chat
  - Data Export API: https://api.talkifai.dev/api/export

Security Warning: API keys grant full access to your organization.

✅ Copy the key immediately and store in a password manager
✅ Use environment variables in your application
❌ Never commit to version control (add to .gitignore)
❌ Never expose in client-side code
❌ Never share via email or chat

After Generation:

Key appears in the “Existing Keys” list on the right
Shows: Name, prefix (e.g., abc123••••••••), created date, expires date, status
Can be revoked anytime by clicking Delete (trash icon)

API Key Format

TalkifAI API keys are random strings (no special prefix like tk_live_). Example: abc123def456... (64 characters)

Using API Keys

Include the API key in the x-api-key header:

curl https://api.talkifai.dev/api/agents \
  -H "x-api-key: your_api_key_here"

// JavaScript example
const response = await fetch('https://api.talkifai.dev/api/agents', {
  headers: {
    'x-api-key': process.env.TALKIFAI_API_KEY,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

# Python example
import httpx

headers = {
    "x-api-key": os.environ["TALKIFAI_API_KEY"],
    "Content-Type": "application/json"
}

response = httpx.get(
    "https://api.talkifai.dev/api/agents",
    headers=headers
)

API Key Features

Feature	Description
Organization-scoped	Keys are tied to a specific organization
Rate limiting	1000 requests per hour (default)
Expiration	1 year from creation (default)
Metadata	Stores creator, creation date, org ID

Organization Context

All API operations are scoped to your active organization.

Session-Based (Studio Users)

The active organization is stored in the session:

const session = await auth.api.getSession({ headers });

if (session) {
  const orgId = session.session.activeOrganizationId;
  console.log("Active org:", orgId);
}

Users can switch organizations in the Studio UI, which updates activeOrganizationId.

API Key Authentication

API keys are automatically scoped to the organization they were created in:

// When creating an API key
const apiKeyData = await auth.api.createApiKey({
  body: {
    name: "Production Backend",
    userId: session.user.id,
    metadata: {
      organizationId: "org_abc123",  // Key is scoped to this org
    }
  }
});

All requests with this key automatically operate within that organization.

Environment Variables

Store credentials securely as environment variables:

# .env.local (development)
# .env.production (production)

# API Key (for server-to-server)
TALKIFAI_API_KEY=your_api_key_here

# Base URL
TALKIFAI_BASE_URL=https://api.talkifai.dev

Never commit .env files to version control. Add them to .gitignore:

# .gitignore
.env
.env.local
.env.production

Verifying Your API Key

Test your API key with a simple request:

curl https://api.talkifai.dev/api/agents \
  -H "x-api-key: $TALKIFAI_API_KEY"

Success Response:

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Customer Support Bot",
      "description": "Handles customer inquiries"
    }
  ]
}

Error Response (Invalid Key):

{
  "error": "Unauthorized - Invalid or missing API key"
}

Revoking API Keys

To revoke a key:

Go to Studio → Organization → API Keys
Find the key in the “Existing Keys” list (right column)
Click Delete (trash icon with red button)
Confirm deletion in the dialog: “Are you sure you want to delete this API key?”

Revoked keys immediately return 401 Unauthorized on all requests.

Irreversible Action: Once revoked, the key cannot be recovered. You’ll need to generate a new key and update your applications.

Security Best Practices

Rotate Keys Regularly

Generate new API keys every 90 days. Delete old keys after rotation.

Use Separate Keys

Use different keys for development, staging, and production environments.

Monitor Active Keys

Check Organization → API Keys regularly. Revoke unused keys immediately.

Never Log Keys

Never log API keys in application logs. Redact sensitive headers.

Use Environment Variables

Store keys in environment variables, not in code or config files.

Limit Key Permissions

Create separate keys for different services with minimal required access.

Error Codes

Status	Error	Description
`401`	`Unauthorized`	Missing or invalid API key / session
`401`	`Invalid API key`	API key is malformed or revoked
`403`	`Forbidden`	Valid auth but insufficient permissions
`403`	`Not a member of the selected organization`	User/org mismatch
`429`	`Rate limit exceeded`	Too many requests (API keys only)

Organization Management — Manage organizations and members
API Keys — Detailed API key management guide
Get Agent — Example API endpoint
Initiate Call — Example API endpoint

Overview

Agents

Voice Calls

Export

Text Chat

Batch Calling

Custom Functions

Webhooks

Overview

Session-Based Authentication

How It Works

Example (Server-Side)

Example (Client-Side)

API Key Authentication

Generating an API Key (Via Studio UI)

API Key Format

Using API Keys

API Key Features

Organization Context

Session-Based (Studio Users)

API Key Authentication

Environment Variables

Verifying Your API Key

Revoking API Keys

Security Best Practices

Rotate Keys Regularly

Use Separate Keys

Monitor Active Keys

Never Log Keys

Use Environment Variables

Limit Key Permissions

Error Codes

​Overview

​Session-Based Authentication

​How It Works

​Example (Server-Side)

​Example (Client-Side)

​API Key Authentication

​Generating an API Key (Via Studio UI)

​API Key Format

​Using API Keys

​API Key Features

​Organization Context

​Session-Based (Studio Users)

​API Key Authentication

​Environment Variables

​Verifying Your API Key

​Revoking API Keys

​Security Best Practices

Rotate Keys Regularly

Use Separate Keys

Monitor Active Keys

Never Log Keys

Use Environment Variables

Limit Key Permissions

​Error Codes

​Related Documentation

Overview

Session-Based Authentication

How It Works

Example (Server-Side)

Example (Client-Side)

API Key Authentication

Generating an API Key (Via Studio UI)

API Key Format

Using API Keys

API Key Features

Organization Context

Session-Based (Studio Users)

API Key Authentication

Environment Variables

Verifying Your API Key

Revoking API Keys

Security Best Practices

Error Codes

Related Documentation