Authentication

Overview

Every request to the Dispatch Tickets API must be authenticated. The method you use depends on where the request originates:

API Keys

API keys are the primary way to authenticate server-side requests. They identify your account and grant access to all brands (workspaces) under it.

Creating an API Key

Generate API keys from the admin dashboard under Settings → API Keys → Create Key. You can also create them programmatically:

const key = await dispatch.apiKeys.create({
  name: 'Production Backend',
});

// Save key.secret securely - it's only shown once
console.log(key.secret); // 'sk_live_...'

Using API Keys

Pass the API key in the Authorization header as a Bearer token:

curl https://dispatch-tickets-api.onrender.com/v1/brands \
  -H "Authorization: Bearer sk_live_your_api_key"

With the SDK, pass it during initialization:

import { DispatchTickets } from '@dispatchtickets/sdk';

const dispatch = new DispatchTickets({
  apiKey: process.env.DISPATCH_API_KEY,
});

Key Types

Session Auth (Admin UI)

The admin dashboard at app.dispatchtickets.com uses session-based authentication via magic links. This is designed for team members who manage tickets through the browser.

How It Works

1. User enters their email on the login page
2. A magic link is sent to their inbox
3. Clicking the link creates a session cookie
4. Subsequent requests use the session cookie automatically

Session Endpoints

// 1. Request a magic link
POST /v1/auth/magic-link
{ "email": "[email protected]" }

// 2. User clicks link, which calls:
POST /v1/auth/verify
{ "token": "ml_abc123..." }
// Returns: { session, account, organization }

// 3. Check current session
GET /v1/auth/session
// Returns: { account, organization, member }

// 4. Logout
POST /v1/auth/logout

Sessions are scoped to an organization. Team members can switch between organizations using the org switcher in the dashboard.

Portal Tokens

Portal tokens let you build customer-facing ticket portals embedded in your own application. They grant limited access scoped to a single customer's tickets.

Generating a Portal Token

Generate tokens server-side using your API key. Never expose your API key to the browser.

// Server-side: generate token for a specific customer
const token = await dispatch.portal.createToken('br_abc123', {
  customerEmail: '[email protected]',
  customerName: 'Jane Doe', // Optional
  expiresIn: '24h',         // Token lifetime
});

// Send token.accessToken to your frontend
// res.json({ portalToken: token.accessToken });

Using Portal Tokens

On the frontend, use the portal token to authenticate API calls on behalf of the customer:

// Browser-side: use portal token for customer requests
const response = await fetch(
  'https://dispatch-tickets-api.onrender.com/v1/portal/tickets',
  {
    headers: {
      'Authorization': 'Bearer pt_abc123...',
    },
  }
);

const { tickets } = await response.json();
// Customer only sees their own tickets

Portal Token Scope

Portal tokens are intentionally limited. A customer can:

• View their own tickets
• Create new tickets
• Add comments to their tickets
• Upload attachments

They cannot view other customers' tickets, access brand settings, or perform admin actions.

Best Practices

Keep API keys secret

Never expose API keys in client-side code, public repositories, or browser requests. Use environment variables and server-side proxies.

Use the right auth method

Rotate keys regularly

Create a new API key, update your services to use it, then revoke the old key. The dashboard lets you have multiple active keys to support zero-downtime rotation.

Scope portal tokens tightly

Set short expiration times on portal tokens (e.g., 24 hours) and generate fresh tokens on each page load. This limits the blast radius if a token is intercepted.