> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privetag.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Authentication for PriveTag B2A API

# API Key Authentication

All PriveTag B2A API requests require authentication via API key.

## Getting Your API Key

1. Sign up at [privetag.com/developers](https://privetag.com/developers)
2. Navigate to **API Keys** section
3. Click **Create New Key**
4. Configure your key settings

<Warning>
  Your API key is shown only once during creation. Store it securely!
</Warning>

## Using Your API Key

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

```bash theme={null}
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

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

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Keys Secret">
    * Never expose API keys in client-side code
    * Use environment variables
    * Don't commit keys to version control
  </Accordion>

  <Accordion title="Use Separate Keys">
    Create different keys for:

    * Development vs Production
    * Different applications
    * Different team members
  </Accordion>

  <Accordion title="Monitor Usage">
    * Check usage in the dashboard regularly
    * Set up alerts for quota warnings
    * Review access logs for unusual activity
  </Accordion>

  <Accordion title="Rotate Keys">
    * Rotate keys periodically
    * Revoke compromised keys immediately
    * Use the dashboard to create new keys before revoking old ones
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Rate Limits" icon="gauge" href="/authentication/rate-limits">
    Learn about rate limiting and quotas
  </Card>

  <Card title="Webhooks" icon="webhook" href="/authentication/webhooks">
    Set up webhook callbacks
  </Card>
</CardGroup>