Skip to main content
GET
/
api
/
v1
/
oauth
/
{provider}
/
authorize
Authorize Provider
curl --request GET \
  --url https://api.example.com/api/v1/oauth/{provider}/authorize
{
  "authorization_url": "<string>",
  "state": "<string>",
  "status_code": 123,
  "detail": "<string>"
}

​
Overview

This endpoint starts the OAuth authorization process for connecting a user to a wearable data provider. It returns an authorization URL where the user should be redirected to authenticate with the provider.
1

Call authorize endpoint

Request authorization URL with user ID and provider name
2

Redirect user

Send user to the returned authorization_url to authenticate
3

Provider redirects back

Provider redirects to callback endpoint with authorization code

​
Path Parameters

​
provider
string
required
Provider identifier. Must be one of:
  • apple - Apple Health
  • samsung - Samsung Health
  • google - Google Fit
  • garmin - Garmin Connect
  • polar - Polar Flow
  • suunto - Suunto App
  • whoop - WHOOP
  • strava - Strava
  • oura - Oura Ring

​
Query Parameters

​
user_id
string
required
UUID of the user to connect to the provider
​
redirect_uri
string
Optional URL to redirect to after successful authorization. If not provided, redirects to default success page.

​
Response

​
authorization_url
string
required
The OAuth authorization URL where the user should be redirected to authenticate
​
state
string
required
CSRF protection state parameter that will be validated in the callback

​
Examples

curl -X GET "https://api.openwearables.com/api/v1/oauth/garmin/authorize?user_id=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response Example

{
  "authorization_url": "https://connect.garmin.com/oauthConfirm?oauth_token=abc123def456&oauth_callback=https%3A%2F%2Fapi.openwearables.com%2Fapi%2Fv1%2Foauth%2Fgarmin%2Fcallback",
  "state": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIiwicHJvdmlkZXIiOiJnYXJtaW4ifQ"
}

​
Error Responses

​
status_code
integer
HTTP status code indicating the error type
​
detail
string
Human-readable error message

​
400 Bad Request

Returned when the provider does not support OAuth authentication. 
{
  "detail": "Provider 'apple' does not support OAuth"
}

​
422 Validation Error

Returned when required parameters are missing or invalid. 
{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "user_id"],
      "msg": "Field required"
    }
  ]
}

​
OAuth Flow

After receiving the authorization URL:
  1. Redirect User: Send the user to the authorization_url
  2. User Authenticates: User logs in and grants permissions on provider’s site
  3. Provider Redirects: Provider redirects back to the callback endpoint
  4. Token Exchange: Callback endpoint exchanges authorization code for access tokens
  5. Data Sync: Background job automatically syncs user’s health data

​
Notes

  • The state parameter is stored in Redis and validated during callback to prevent CSRF attacks
  • State expires after 10 minutes if not used
  • Some providers (like Apple Health) use SDK-based authentication and don’t support this OAuth flow
  • The authorization URL format varies by provider but always includes necessary OAuth parameters

Build docs developers (and LLMs) love

Get started for freeTalk to us