Authentication

All API requests require authentication using an API key. This guide explains how to obtain and use your credentials.

Getting API Keys

Generate an API Key

Access API Settings

Create New Key

Click Create API Key.

Configure Key

Set the key options:

Name - A descriptive name (e.g., "Production Server")
Permissions - Select which operations the key can perform
Expiration - Optional expiration date

Copy Your Key

Copy the API key immediately. It won't be shown again.

Store Securely

Your API key provides access to your account. Store it securely and never commit it to version control.

Using Your API Key

Bearer Token Authentication

Include your API key in the Authorization header:

curl https://api.bookwell.app/v1/services \
  -H "Authorization: Bearer bw_live_abc123..."

Key Prefixes

API keys have prefixes indicating their type:

Prefix	Type	Use
`bw_live_`	Live/Production	Production applications
`bw_test_`	Sandbox/Test	Development and testing

Always use test keys during development. Switch to live keys only in production.

Key Permissions

Available Scopes

Configure what each API key can access:

Scope	Description
`read:services`	List and view services
`read:appointments`	View appointment data
`write:appointments`	Create and modify appointments
`read:customers`	View customer data
`write:customers`	Create and modify customers
`read:therapists`	View therapist data
`webhooks`	Manage webhook subscriptions

Example Key Configuration

A booking integration might need:

read:services - To display available services
read:therapists - To show provider availability
write:appointments - To create bookings
write:customers - To create customer records

Security Best Practices

Environment Variables

Store API keys in environment variables:

# .env (never commit this file)
BOOKWELL_API_KEY=bw_live_abc123...

Access in your code:

const apiKey = process.env.BOOKWELL_API_KEY;

Never Expose Keys

Never include API keys in:

Client-side JavaScript
Mobile app code
Public repositories
Log files
Error messages

Rotate Keys Regularly

For security, rotate API keys periodically:

Create a new key
Update your application to use the new key
Verify everything works
Delete the old key

Managing API Keys

Viewing Keys

From Settings > API, you can see:

Key name and partial key
Created date
Last used date
Permissions

Revoking Keys

To revoke a key:

Go to Settings > API
Find the key
Click Revoke
Confirm revocation

Revoking a key is immediate and permanent. Ensure your application is updated first.

Error Responses

Invalid Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked"
  }
}

Missing Key

{
  "error": {
    "code": "authentication_required",
    "message": "No API key provided. Include Authorization header."
  }
}

Insufficient Permissions

{
  "error": {
    "code": "insufficient_permissions",
    "message": "This API key does not have permission to perform this action",
    "details": {
      "required_scope": "write:appointments"
    }
  }
}

OAuth (Coming Soon)

For applications that need to act on behalf of users, OAuth support is planned:

Authorization code flow
Access and refresh tokens
User-consented permissions

IP Whitelisting

For additional security, restrict keys to specific IPs:

Go to Settings > API > IP Restrictions
Add allowed IP addresses or ranges
Save changes

Requests from non-whitelisted IPs will be rejected.

Testing Authentication

Verify your setup:

curl https://api.bookwell.app/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "data": {
    "business_id": "biz_abc123",
    "business_name": "Wellness Spa",
    "key_name": "Production Server",
    "permissions": ["read:services", "write:appointments"]
  }
}

Learn how to authenticate requests to the Bookwell API.