OAuth for marketplace apps

HowdyBell uses the OAuth 2.0 authorization code flow. Your app exchanges an authorization code for an access token.

Step 1: Redirect the user

Send the user's browser to the authorization URL:

https://howdybell.com/oauth/authorize

Include these query parameters:

• client_id: Your app's client ID.
• redirect_uri: One of your registered redirect URIs.
• response_type: Must be code.
• scope: Space-separated list of scopes. Must be a subset of your app's declared scopes.
• state: A random string to prevent CSRF attacks.
• code_challenge: (Optional) PKCE challenge.
• code_challenge_method: (Optional) The PKCE method, S256.

Example:

https://howdybell.com/oauth/authorize?client_id=abc123&redirect_uri=https://yourapp.com/callback&response_type=code&scope=contacts.readonly+contacts.write&state=xyz789

The user sees a consent screen. They pick a location and click Allow.

Step 2: Handle the redirect

HowdyBell redirects the user to your redirect_uri with:

• code: The authorization code.
• state: The same state string you sent.

If the user denies access, you receive error=access_denied.

Step 3: Exchange the code for a token

Send a POST request to the token endpoint:

curl -X POST https://howdybell.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=abc123 \
  -d client_secret=your_secret \
  -d redirect_uri=https://yourapp.com/callback \
  -d code=auth_code_from_redirect \
  -d code_verifier=your_pkce_verifier

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJh...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "def50200a1b2..."
}

Access tokens expire after 1 day. Refresh tokens expire after 1 year.

Step 4: Use the access token

Include the access token in the Authorization header for API calls:

curl https://howdybell.com/api/v1/contacts?location_id=123 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The token is locked to the location the user selected during authorization.

Refresh the token

When the access token expires, use the refresh token:

curl -X POST https://howdybell.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d client_id=abc123 \
  -d client_secret=your_secret \
  -d refresh_token=$REFRESH_TOKEN

This returns a new access token and a new refresh token.