Getting started

This guide walks you from zero to a working request against the Carebit Developer Platform, and shows how to receive webhook events.

1. Create a developer project

First, make sure you have already been added as a staff member to the Carebit organisation that you want to build an integration for. If you don't already have a staff member account, please speak to the administrator of your Carebit organisation as they can add to you as a staff member with a developer role in Settings > Staff members within Carebit.

Sign in to Carebit and go to Settings > Developer platform > Projects. Click to create a new project and give it a descriptive name. You can now pick the API scopes your project will need (for example bookings.read, bookings.create) and the webhook events you want to receive. Save the project.

2. Create an API credential

Inside the project, open the API credentials tab and click Create credential. Copy the client_id and client_secret returned by the form. The client_secret is shown once. If you lose it, rotate the credential rather than creating a duplicate project. Client secrets use a carebit_cs_live_... prefix so leaked values can be classified by secret scanners. Customer credentials work against the API at https://api.carebit.co.

3. Set up webhooks

If your integration needs to react when something happens in Carebit, register an HTTPS endpoint on the project. Webhooks do not use the access token from the next step; Carebit POSTs signed JSON to your URL when a subscribed event occurs.

Open Settings > Developer platform > Projects > (your project) > Webhook endpoints, click Add endpoint, and paste the HTTPS URL that will receive deliveries. Copy the signing secret shown when the endpoint is created. The secret is shown once and uses a carebit_whsec_live_... prefix. If you lose it, rotate the secret from the dashboard rather than creating a duplicate endpoint.

Subscribe the endpoint to the event types you need. Webhook subscriptions are independent from API scopes: selecting an event type authorizes that endpoint to receive the payload. Verify the Carebit-Signature header against the exact raw request body before you trust the payload, then return a 2XX within 20 seconds.

Use Send test event in the dashboard to deliver a test payload with livemode: false while you build your receiving endpoint.

See Webhook setup for the delivery envelope and headers, Webhook signatures for verification, and Webhook retries for retry behavior. The event catalog is on the webhooks page.

4. Exchange the credential for an access token

The token endpoint is form-encoded per the OAuth2 spec. Do not send JSON and do not send an Authorization: Bearer header.

curl -X POST "https://api.carebit.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CAREBIT_CLIENT_ID" \
  --data-urlencode "client_secret=$CAREBIT_CLIENT_SECRET" \
  --data-urlencode "scope=organization.read bookings.read"

The scope value must be a subset of the scopes on the developer project. If you omit scope, the token receives every scope on the project. Requesting a scope the project does not have returns 400 with error.code invalid_scope.

The response contains a short-lived access_token and a rotating refresh_token. Access tokens live for about one hour. See Authentication for the full scope rule, token refresh, and revocation.

5. Make your first request

Call GET /v1/token to confirm the access token works. Any valid token can call this endpoint. It does not require organization.read.

curl "https://api.carebit.co/v1/token" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

A 200 OK with a JSON body means the credential and token are healthy. From here, browse the API reference for every endpoint you can call.