OAuth 2.0

OnboardingHub supports the OAuth 2.0 authorization code grant flow, which is the recommended method for third-party applications that need to access the API on behalf of a user.

Overview

The flow works like this:

1. Your application redirects the user to OnboardingHub's authorization page
2. The user selects a workspace and approves the requested scopes
3. OnboardingHub redirects back to your app with an authorization code
4. Your app exchanges the code for an access token and refresh token
5. Use the access token to make API requests

Registering your application

1. Navigate to your workspace's Developer Settings
2. Go to OAuth Applications
3. Click New OAuth Application
4. Fill in the details:
   • Name -- displayed to users during authorization
   • Redirect URI -- where OnboardingHub sends the authorization code
   • Scopes -- which permissions your app needs
5. Save and note your Client ID and Client Secret

Authorization code flow

Step 1: Redirect to authorization

Send the user to the OnboardingHub authorization endpoint:

GET https://onboarding-hub.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=contacts_read+contacts_write+enrollments_read

Parameters:

Available scopes (OAuth format):

Step 2: User approves the request

The user sees a consent screen showing your application name and requested permissions. They select a workspace and click "Authorize."

Step 3: Exchange the code for tokens

OnboardingHub redirects back to your redirect_uri with a code parameter:

https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=YOUR_STATE

Exchange the code for tokens:

curl -X POST https://onboarding-hub.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback"

import requests

response = requests.post("https://onboarding-hub.com/oauth/token", data={
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://yourapp.com/callback",
})
tokens = response.json()
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]

const response = await fetch("https://onboarding-hub.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code: "AUTHORIZATION_CODE",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
    redirect_uri: "https://yourapp.com/callback",
  }),
});
const tokens = await response.json();

Response:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "def456...",
  "scope": "contacts_read contacts_write enrollments_read",
  "created_at": 1707436800
}

Step 4: Use the access token

Include the access token in API requests just like an API key:

curl -H "Authorization: Bearer eyJhbGci..." \
  https://onboarding-hub.com/api/v1/contacts

Refreshing tokens

Access tokens expire after 2 hours. Use the refresh token to get a new access token without re-prompting the user:

curl -X POST https://onboarding-hub.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=def456..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Token introspection

Check whether a token is valid and see its metadata:

curl -X POST https://onboarding-hub.com/oauth/introspect \
  -d "token=eyJhbGci..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Revoking tokens

Revoke an access or refresh token:

curl -X POST https://onboarding-hub.com/oauth/revoke \
  -d "token=eyJhbGci..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Token lifetimes

Security considerations

• Always use HTTPS for redirect URIs in production
• Store client secrets securely -- never expose them in client-side code
• Use the state parameter to prevent CSRF attacks
• Rotate refresh tokens when possible

Next steps

• Authentication -- API key authentication
• Endpoints reference -- available API endpoints