Authentication

Learn how to authenticate to access the Booking Platform API

Authentication Methods

1. Bearer Token (Recommended)

Use an API Key in the header:

curl -X GET "https://api.booking-platform.com/v1/bookings" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

2. API Key Header

Use the API Key directly:

curl -X GET "https://api.booking-platform.com/v1/bookings" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

3. Basic Auth

For some internal use cases:

curl -X GET "https://api.booking-platform.com/v1/bookings" \
  -H "Authorization: Basic base64(email:api_key)"

---

API Keys

Create an API Key

1. Go to Settings > API Keys
2. Click Create New Key
3. Set a name and select permissions
4. Copy the Key and store it securely

API Key Types

Type	Permissions	Use Case
Full Access	All permissions	Server-side
Read Only	Read only	Analytics
Bookings	Manage bookings	Booking Widget
Customers	Manage customers	CRM Integration

Best Practices

⚠️ Security Warning:

1. Store API Key securely
   - Do not store in code
   - Use Environment Variables

2. Use minimum permissions
   - Select only necessary permissions

3. Rotate Keys regularly
   - Every 90 days

4. Monitor usage
   - Check API Logs regularly

---

Making Authenticated Requests

Example: Create a Booking

const response = await fetch('https://api.booking-platform.com/v1/bookings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_REDACTED',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerId: 'cust_123456',
    serviceId: 'svc_789012',
    staffId: 'staff_345678',
    dateTime: '2024-01-15T10:00:00Z',
    notes: 'Special appointment request',
  }),
});

const data = await response.json();
console.log(data);

Example: Get Bookings List

const response = await fetch(
  'https://api.booking-platform.com/v1/bookings?page=1&limit=20',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer sk_test_REDACTED',
    },
  }
);

const { data, pagination } = await response.json();
console.log(`Found ${pagination.total} bookings`);

---

Token Refresh

For OAuth2:

// Refresh Token
const response = await fetch('https://api.booking-platform.com/v1/auth/refresh', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    refreshToken: 'your_refresh_token',
  }),
});

const { accessToken, expiresIn } = await response.json();
// Store the new accessToken
localStorage.setItem('accessToken', accessToken);

---

Error Handling

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API Key is invalid or expired"
  }
}

How to fix:

1. Check if the API Key is correct
2. Check if the Key has been revoked
3. Create a new Key if necessary

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this endpoint"
  }
}

How to fix:

1. Check the API Key permissions
2. Use a Key with sufficient permissions

---

Security Best Practices

1. Environment Variables

# .env (do not commit!)
API_KEY=sk_test_REDACTED

// In code
const apiKey = process.env.API_KEY;

2. HTTPS Only

// Ensure HTTPS is used
if (process.env.NODE_ENV === 'production' && !req.secure) {
  return res.redirect(`https://${req.hostname}${req.url}`);
}

3. Rate Limiting

// Limit number of requests
const rateLimit = {
  windowMs: 60 * 1000, // 1 minute
  maxRequests: 100,
};

4. Audit Logs

// Log API usage
async function logApiAccess(req: Request, res: Response) {
  await db.apiLogs.create({
    apiKey: req.apiKey,
    endpoint: req.path,
    method: req.method,
    ip: req.ip,
    timestamp: new Date(),
  });
}

---

Next Steps

• API Reference — View all endpoint details
• API Tester — Test API directly