API Key Authentication

All PriveTag B2A API requests require authentication via API key.

Getting Your API Key

Sign up at privetag.com/developers
Navigate to API Keys section
Click Create New Key
Configure your key settings

Your API key is shown only once during creation. Store it securely!

Using Your API Key

Include your API key in the x-api-key header with every request:

curl -X POST https://api.privetag.com/api/b2a/recommend \
  -H "x-api-key: pk_a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{"user_profile": {"travel_type": "family"}}'

Key Format

API keys follow this format:

Prefix: pk_ followed by 6 characters (visible in dashboard)
Full Key: 64 character hex string

Example: pk_a1b2c3... (full key is 64 characters)

Endpoint Permissions

When creating an API key, you can specify which endpoints it can access:

Endpoint	Description
`recommend`	Get activity recommendations
`execute_booking`	Create bookings
`inventory`	Check availability
`webhook`	Receive webhook callbacks

Quota and Rate Limits

Each API key has:

Daily Quota: Maximum requests per day (resets at midnight UTC)
Rate Limit: Maximum requests per minute

Plan	Requests/Minute	Daily Quota
Free	10	100
Basic	60	1,000
Premium	300	10,000
Enterprise	Unlimited	Unlimited

Error Codes

Code	HTTP Status	Description
`MISSING_API_KEY`	401	No API key provided in header
`INVALID_API_KEY`	401	API key doesn’t exist or is malformed
`KEY_INACTIVE`	403	API key has been deactivated
`ENDPOINT_NOT_ALLOWED`	403	Key doesn’t have permission for this endpoint
`QUOTA_EXCEEDED`	429	Daily quota reached
`RATE_LIMITED`	429	Too many requests per minute

Error Response Format

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "details": "Maximum 60 requests per minute. Please wait and try again."
}

Best Practices

Keep Keys Secret

Never expose API keys in client-side code
Use environment variables
Don’t commit keys to version control

Use Separate Keys

Create different keys for:

Development vs Production
Different applications
Different team members

Monitor Usage

Check usage in the dashboard regularly
Set up alerts for quota warnings
Review access logs for unusual activity

Rotate Keys

Rotate keys periodically
Revoke compromised keys immediately
Use the dashboard to create new keys before revoking old ones

Webhook Configuration

You can configure a webhook URL for your API key to receive callbacks:

Booking Confirmed: When a booking is successfully created
Voucher Delivered: When voucher email is sent
QR Verified: When guest uses the voucher (Ground Truth event)

Configure webhooks in the API Keys dashboard or contact support.

Next Steps

Rate Limits

Learn about rate limiting and quotas

Webhooks

Set up webhook callbacks

​API Key Authentication

​Getting Your API Key

​Using Your API Key

​Key Format

​Endpoint Permissions

​Quota and Rate Limits

​Error Codes

​Error Response Format

​Best Practices

​Webhook Configuration

​Next Steps

Rate Limits

Webhooks

API Key Authentication

Getting Your API Key

Using Your API Key

Key Format

Endpoint Permissions

Quota and Rate Limits

Error Codes

Error Response Format

Best Practices

Webhook Configuration

Next Steps