Authentication

yAppointment supports two authentication methods: API keys for server-to-server communication and OAuth 2.1 for user-delegated access.

API Keys

API keys are ideal for integrations where you manage the appointment data directly. Create keys in your Admin Settings under Integrations > API Keys.

Key Types

Live Keys (yapp_sk_live_*) — use in production. Charge customers and interact with live data.

Test Keys (yapp_sk_test_*) — sandbox mode. Isolated test companies with no real payments.

Creating an API Key

1. Open Admin Settings
2. Navigate to Integrations > API Keys
3. Click Create New Key
4. Name it (e.g., "Zapier Integration")
5. Copy the key to a secure location (never commit to Git)

Using API Keys

Include your key in the Authorization header:

curl -H "Authorization: Bearer yapp_sk_live_YOUR_KEY" \
     https://api.yappointment.com/api/v1/me

Keys are scoped to a single company. If you're building a multi-company integration, request multiple keys or use OAuth 2.1.

OAuth 2.1

Use OAuth when building third-party integrations (e.g., Zapier, Make.com) where users authorize you to access their appointment data.

Scopes

Request only the scopes your integration needs:

• bookings:read — read bookings and availability
• bookings:write — create, modify, or cancel bookings
• companies:read — read company profile (name, email, phone)
• calendar:read — read calendar events
• calendar:write — create or modify calendar events

Authorization Flow (Authorization Code)

1. Redirect user to the authorization endpoint:

   https://auth.yappointment.com/oauth/authorize?
   response_type=code&
   client_id=YOUR_CLIENT_ID&
   redirect_uri=https://yourapp.com/oauth/callback&
   scope=bookings:read%20bookings:write
   

2. User logs in and approves your app's access

3. Receive an authorization code (valid 10 minutes)

4. Exchange code for an access token:

   curl -X POST https://auth.yappointment.com/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=AUTH_CODE" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "redirect_uri=https://yourapp.com/oauth/callback"
   

5. Receive access token and refresh token (access valid 1 hour)

Using OAuth Tokens

Include the access token in the Authorization header:

curl -H "Authorization: Bearer eyJ0eXAi..." \
     https://api.yappointment.com/api/v1/me

Refreshing Tokens

Access tokens expire after 1 hour. Refresh using the refresh token:

curl -X POST https://auth.yappointment.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Choosing Between API Key and OAuth

| Use Case | Method | Reason | |----------|--------|--------| | Internal integration (your own company) | API Key | Simpler, fewer moving parts | | Third-party app (multiple users) | OAuth 2.1 | Users authorize access, secure | | Webhook verification | Both | Include token in webhook header | | Mobile app backend | OAuth 2.1 | Refresh tokens, scope isolation |

Security Best Practices

1. Never expose keys in frontend code — use a backend proxy
2. Rotate API keys regularly — delete old keys after rotation
3. Use HTTPS only — always transmit tokens over encrypted connections
4. Scope OAuth requests tightly — only request scopes you need
5. Store tokens securely — use environment variables or secure key managers, never version control
6. Implement request signing — for webhooks, verify the X-Signature header