Skip to main content

​
API Keys

All requests to the Open API are authenticated with an API key sent via the api-key HTTP header. 
curl https://api.ticketnation.ph/open-api/v1/me \
  -H "api-key: tn_live_your_api_key_here"

​
Creating an API Key

1

Navigate to API Keys

Go to Organizer Dashboard > Settings > API Keys tab and click + Create Key
2

Fill in details

  • Name — a label for your integration (e.g., “Experia Integration”)
  • Description — what this key is used for
3

Select scopes

Check the permissions your integration needs (see table below)
4

Configure optional settings

  • Callback URL — webhook URL to receive order and event notifications
  • IP Allowlist — comma-separated IPs to restrict key usage (leave empty to allow all)
5

Copy your key

The key is displayed once after creation — store it securely

​
Scopes

Each API key has specific scopes that control what it can access. Request only the scopes you need.
ScopeDashboard LabelAllows
events:readRead EventsList and get events, search venues
events:writeWrite EventsCreate, update, publish, unpublish, archive, delete events. Also required for managing performers, schedules, and brands on your events.
tickets:readRead TicketsList and get ticket types
tickets:writeWrite TicketsCreate, update, publish, mark sold out, delete ticket types
orders:read—List and get orders for your events
webhooks:manageManage WebhooksCreate, update, delete, and test webhooks
The orders:read scope is granted automatically when creating a key with event scopes. It will appear in the dashboard in a future update.

​
Scope Requirements by Resource

ResourceReadWrite
Eventsevents:readevents:write
Performersevents:readevents:write
Schedulesevents:readevents:write
Brandsevents:readevents:write
Ticketstickets:readtickets:write
Ordersorders:read— (read-only)
Venuesevents:read— (search only)
Webhookswebhooks:managewebhooks:manage
If your key lacks a required scope, the API returns 403 FORBIDDEN with code SCOPE_REQUIRED.

​
IP Allowlist

For production keys, you can restrict usage to specific IP addresses or CIDR ranges:
  • Leave empty to allow all IPs
  • Add your server’s public IP(s) for security
  • Supports individual IPs and CIDR notation
Requests from non-allowlisted IPs receive 403 FORBIDDEN.

​
Webhook Security

When Ticketnation sends webhook events to your server, each request includes an HMAC signature for verification.

​
Verifying Webhook Signatures

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

// In your webhook handler:
app.post('/webhooks/ticketnation', (req, res) => {
  const signature = req.headers['x-tn-signature'] as string;
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET!,
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const { type, data } = req.body;
  console.log(`Received ${type}`, data);

  res.status(200).send('OK');
});

​
Webhook Events

EventTrigger
order.completedA buyer completes a purchase for your event
order.refundedAn order is refunded
event.sold_outAll tickets for an event are sold
ticket.inventory_lowA ticket type’s remaining quantity drops below threshold

​
Webhook Payload Format

{
  "type": "order.completed",
  "data": {
    "orderId": "uuid",
    "orderNumber": "TN-20250615-ABC123",
    "eventId": "uuid",
    "totalAmount": 3000,
    "currency": "PHP",
    "quantity": 2,
    "buyerName": "Juan Dela Cruz",
    "buyerEmail": "juan@example.com"
  },
  "timestamp": "2025-06-15T18:30:00.000Z"
}

​
Webhook Reliability

  • Failed deliveries are retried with exponential backoff (up to 3 attempts)
  • Webhooks are auto-disabled after 10 consecutive failures
  • Use the test endpoint to verify your webhook URL works
  • Check delivery history via the API to debug failures

​
Security Best Practices

  1. Rotate keys regularly — create a new key, update your integration, then delete the old one
  2. Use IP allowlists in production
  3. Scope minimally — don’t grant events:write if you only need events:read
  4. Store keys in environment variables, never in code
  5. Verify webhook signatures to prevent spoofed events
  6. Set expiration dates for temporary integrations