OnboardingHub OnboardingHub

Authentication

All OnboardingHub API requests require authentication via a Bearer token in the Authorization header. Two methods are available for obtaining tokens.

API Keys (Custom Connections)

API keys are the simplest way to authenticate. Create them in your workspace's Developer settings to get a long-lived access token for programmatic use.

Creating an API key

  1. Navigate to your workspace's Integrations > Developer
  2. Register a custom connection application
  3. Select the scopes you need
  4. Copy the token -- it is shown only once

Using an API key

Include the token in the Authorization header:

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

require "net/http"
require "json"

uri = URI("https://onboarding-hub.com/api/v1/contacts")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_ACCESS_TOKEN"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end

contacts = JSON.parse(res.body)

import requests

headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
response = requests.get(
    "https://onboarding-hub.com/api/v1/contacts",
    headers=headers
)
contacts = response.json()

const response = await fetch("https://onboarding-hub.com/api/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
  },
});
const contacts = await response.json();

Key security

  • The token is displayed only once at creation. If lost, revoke the key and create a new one
  • Keys can be revoked at any time from Developer Settings
  • Each key has specific scopes limiting what API operations it can perform

Scopes

When creating an API key, you choose which scopes to grant. Only endpoints matching the key's scopes are accessible.

Scope Grants access to
contacts:read List and view contacts
contacts:write Create, update, and delete contacts
organisations:read List and view organisations
organisations:write Create, update, and delete organisations
enrollments:read List and view enrollments
enrollments:write Create, update, and delete enrollments
guides:read List and view published guides
webhooks:manage Full CRUD on webhook endpoints

If you attempt an action that requires a scope your key does not have, you will receive a 403 Forbidden response:

{
  "error": {
    "type": "insufficient_scope",
    "message": "This action requires the 'contacts:write' scope. Your credential does not have this permission."
  }
}

OAuth 2.0

OAuth 2.0 is the recommended authentication method for third-party applications that act on behalf of a user. OnboardingHub implements the authorization code grant flow.

For full details, see OAuth 2.0.

Entitlement requirements

API access requires the api-access entitlement on your workspace's plan. If your plan does not include API access, all API requests will return:

{
  "error": {
    "type": "forbidden",
    "message": "API access is not enabled for this account. Please upgrade your plan."
  }
}

Next steps