API Authentication

​

Authentication Overview

​

API Key Authentication

​

Generating API Keys

1. Access Dashboard: Log in to your Tiquo web dashboard
2. Navigate to Settings: Go to Account Settings > API Access
3. Create Key: Generate a new API key with appropriate permissions
4. Secure Storage: Store your API key securely and never expose it publicly

​

Using API Keys

Authorization: Bearer your_api_key_here
Content-Type: application/json

​

OAuth 2.0 Authentication

​

OAuth Flow

1. Authorization Request: Direct users to Tiquo’s authorization endpoint
2. User Consent: Users grant permission for your application
3. Authorization Code: Receive authorization code from Tiquo
4. Access Token: Exchange authorization code for access token
5. API Requests: Use access token for authenticated API requests

​

Authorization Endpoints

Authorization URL: https://api.tiquo.com/oauth/authorize
Token URL: https://api.tiquo.com/oauth/token

​

Permission Scopes

​

Available Scopes

• bookings:read - Read booking and appointment data
• bookings:write - Create and modify bookings
• customers:read - Access customer information
• customers:write - Modify customer profiles
• payments:read - View payment and transaction data
• payments:write - Process payments and refunds
• analytics:read - Access business analytics and reports
• staff:read - View staff information and schedules
• staff:write - Modify staff data and assignments

​

Scope Best Practices

• Minimal Permissions: Request only the scopes your application needs
• Scope Validation: Verify your application has required scopes before making requests
• Permission Updates: Update scopes when application functionality changes
• User Communication: Clearly explain why each permission is needed

​

Rate Limiting

​

Rate Limits

• Standard Limits: 1000 requests per hour per API key
• Burst Limits: Up to 100 requests per minute for short bursts
• Enterprise Limits: Higher limits available for enterprise accounts
• Custom Limits: Contact support for custom rate limit requirements

​

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​

Handling Rate Limits

• Exponential Backoff: Implement exponential backoff for rate limit errors
• Request Optimization: Batch requests where possible to reduce API calls
• Caching: Cache API responses to reduce unnecessary requests
• Monitor Usage: Track your API usage to avoid hitting limits

​

Error Handling

​

HTTP Status Codes

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request format or parameters
• 401 Unauthorized - Invalid or missing authentication
• 403 Forbidden - Insufficient permissions for requested action
• 404 Not Found - Requested resource does not exist
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error occurred

​

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request parameters are invalid",
    "details": {
      "field": "customer_id",
      "issue": "Customer ID must be a valid UUID"
    }
  }
}

​

Security Best Practices

​

API Key Security

• Environment Variables: Store API keys in environment variables
• Key Rotation: Regularly rotate API keys for enhanced security
• Access Monitoring: Monitor API key usage for suspicious activity
• Revocation: Immediately revoke compromised API keys

​

Request Security

• HTTPS Only: All API requests must use HTTPS encryption
• Input Validation: Validate all input data before sending requests
• Error Logging: Log API errors for debugging without exposing sensitive data
• Timeout Handling: Implement appropriate request timeouts

​

Testing & Development

​

Sandbox Environment

• Test API Keys: Use separate API keys for development and testing
• Test Data: Sandbox environment with test customers and bookings
• Safe Testing: Test all functionality without affecting live data
• Production Migration: Easy migration from testing to production environment

​

Development Tools

• API Explorer: Interactive API documentation and testing interface
• Postman Collection: Pre-configured Postman collection for API testing
• Code Examples: Sample code in multiple programming languages
• SDK Libraries: Official SDKs for popular frameworks and languages

​

Webhooks & Real-time Events

​

Event Subscriptions

• Booking Events: Real-time notifications for booking changes
• Payment Events: Instant notifications for payment processing
• Customer Events: Updates when customer data changes
• Staff Events: Notifications for staff schedule and availability changes

​

Webhook Configuration

{
  "url": "https://your-app.com/webhooks/tiquo",
  "events": ["booking.created", "payment.completed"],
  "secret": "webhook_secret_for_verification"
}