OtesseOtesseDocs

OAuth 2.0 Flow

OAuth 2.0 is used when your application needs to act on behalf of a user (customer or team member). This is the appropriate authentication method for customer-facing integrations and third-party apps.

Flow Overview

Otesse implements the Authorization Code flow:

1. Your app redirects user to Otesse authorization URL
2. User logs in and grants permission
3. Otesse redirects back to your app with an authorization code
4. Your server exchanges the code for access + refresh tokens
5. Use the access token to make API calls on the user's behalf

Step 1: Register Your Application

Before using OAuth, register your application:

  1. Go to Settings > Integrations > OAuth Apps
  2. Click Register App
  3. Provide: app name, description, redirect URI(s), logo
  4. You receive a clientid and clientsecret

Step 2: Authorization Request

Redirect the user to the authorization endpoint:

GET https://auth.otesse.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=bookings:read customers:read
  &state=random_csrf_token
ParameterRequiredDescription
client_idYesYour application's client ID
redirect_uriYesMust match a registered redirect URI
response_typeYesAlways code
scopeYesSpace-separated list of requested scopes
stateRecommendedRandom string to prevent CSRF attacks

Step 3: User Authorization

The user sees a consent screen showing:

  • Your application name and logo
  • The permissions (scopes) being requested
  • Options to approve or deny

Step 4: Token Exchange

After the user approves, they are redirected to your redirect_uri with an authorization code:

GET https://yourapp.com/callback?code=AUTH_CODE&state=random_csrf_token

Exchange the code for tokens:

curl -X POST https://auth.otesse.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

Response:

{
  "access_token": "otesse_at_abc123...",
  "refresh_token": "otesse_rt_def456...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "bookings:read customers:read"
}

Step 5: Making API Calls

Use the access token in the Authorization header:

curl -X GET https://api.otesse.com/v1/bookings \
  -H "Authorization: Bearer otesse_at_abc123..."

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to get a new access token:

curl -X POST https://auth.otesse.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "otesse_rt_def456...",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

Refresh tokens are valid for 30 days. If a refresh token expires, the user must re-authorize.

Rate LimitingCustomers API