Carebit API

OAuth

Create, inspect, and revoke OAuth 2.0 access tokens.

Endpoints

Scroll this page to read every OAuth endpoint, or jump to one below.

post/oauth/revokeRevoke an access or refresh token
post/oauth/tokenCreate an access token
get/v1/tokenGet the access token used on this request

post/oauth/revoke

Revoke an access or refresh token

This operation is idempotent. It returns 200 {} whether or not the token was valid, which prevents token enumeration.

Request body

application/x-www-form-urlencoded

client_idstring
The OAuth application UID.
client_secretstring
The OAuth application secret.
tokenstringrequired
The access or refresh token value to revoke.
token_type_hintstring
The type of token supplied in token.
Allowed values: access_token | refresh_token

Responses

200

The token was revoked, or was already invalid.

valueobject
An empty object returned whether or not the token was valid. This prevents token enumeration.

Example

{}

401

The client credentials are invalid.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Request

curl -X POST "https://api.carebit.co/oauth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=example_client_id" \
  --data-urlencode "client_secret=carebit_cs_live_example_client_secret" \
  --data-urlencode "token=carebit_at_live_example_access_token" \
  --data-urlencode "token_type_hint=access_token"

200 response

{}

401 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

post/oauth/token

Create an access token

Exchange client credentials or a refresh token for an access token. Send client_id and client_secret using HTTP Basic authentication or as request body fields. This endpoint does not require a Bearer token; it issues one.

Request body

application/x-www-form-urlencoded

client_idstring
The OAuth application UID. Omit when passing credentials via HTTP Basic.
client_secretstring
The OAuth application secret. Omit when passing credentials via HTTP Basic.
grant_typestringrequired
The OAuth grant type to exchange for an access token.
Allowed values: client_credentials | refresh_token
refresh_tokenstring
The refresh token issued by a previous grant. Required only for grant_type=refresh_token.
scopestring
The space-separated list of requested scopes. Must be a subset of the developer project's scopes. Defaults to the project's full scope set for client_credentials. Requesting a scope the project does not have returns invalid_scope. Ignored for refresh_token.

Responses

200

The access token was created. The response includes a refresh_token for both supported grant types.

access_tokenstringrequired
The issued Bearer access token.
created_atintegerrequired
The Unix timestamp at which the token was issued.
expires_inintegerrequired
The lifetime of the access token, in seconds.
refresh_tokenstring
The refresh token. A new one is issued with each access token.
scopestring
The space-separated list of granted scopes.
token_typestringrequired
The authentication scheme to use in the Authorization header.

Example

{
  "access_token": "carebit_at_live_example_access_token",
  "created_at": 1767193200,
  "expires_in": 3600,
  "refresh_token": "carebit_rt_live_example_refresh_token",
  "scope": "bookings.read bookings.create",
  "token_type": "Bearer"
}

400

The token request is malformed, or one or more requested scopes are not on the project (invalid_scope).

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401

The client credentials are invalid.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403

The project is disabled or archived, or the Organization does not have the developer_platform entitlement.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429

Too many token requests.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Request

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

200 response

{
  "access_token": "carebit_at_live_example_access_token",
  "created_at": 1767193200,
  "expires_in": 3600,
  "refresh_token": "carebit_rt_live_example_refresh_token",
  "scope": "bookings.read bookings.create",
  "token_type": "Bearer"
}

400 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

get/v1/token

Get the access token used on this request

Returns the current access token, the Organization and project it belongs to, and the granted scopes. Any valid access token can call this endpoint. It does not require organization.read. The response does not include the token secret.

Responses

200

The requested Token.

created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
expires_atstring · date-timerequired
The time after which this access token is no longer valid, as an ISO 8601 timestamp in UTC.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
linksobjectrequired
URLs to related resources.
- organizationstring · urirequired
  The Organization this access token belongs to. Reading that resource requires organization.read.
- selfstring · urirequired
  This access token.
livemodebooleanrequired
true when the token was issued in the live Carebit environment. false for test tokens.
objectanyrequired
Discriminator value emitted at object.
organizationobjectrequired
A summary of the Organization this access token belongs to. Address, email, and phone are omitted so a token without organization.read cannot read those fields.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- namestringrequired
  The display name of the Organization.
- objectanyrequired
  Discriminator value emitted at object.
projectobjectrequired
A summary of the developer project that issued this access token.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- namestringrequired
  The display name of the developer project.
- objectanyrequired
  Discriminator value emitted at object.
scopesarrayrequired
The OAuth scopes granted to this access token, sorted alphabetically. This is a subset of the developer project's scopes.
- itemsstring
  An OAuth scope granted to this access token.
  Allowed values: availability_periods.create | availability_periods.delete | availability_periods.update | availability_slots.read | bookings.cancel | bookings.create | bookings.read | bookings.update | clinician_agenda.read | clinicians.read | digital_form_responses.create | digital_form_responses.read | digital_forms.read | expirable_files.read | human_tasks.create | invoices.read | leads.create | leads.read | leads.update | letters.create | letters.read | lists.create | lists.delete | lists.read | lists.update | locations.read | notes.create | notes.read | notes.update | organization.read | organization.search | patient_connections.create | patient_connections.read | patient_connections.update | patients.create | patients.read | patients.update | payments.read | payors.create | payors.read | payors.update | reports.create | services.read | staff_members.read | test_results.create | test_results.read | transmissions.read | webhook_endpoints.create | webhook_endpoints.delete | webhook_endpoints.read | webhook_endpoints.update

Example

{
  "id": "50d3e61c-c488-42b5-850c-230f3df82fb1",
  "object": "token",
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "links":  … }
    "organization": "https://api.carebit.co/v1/organization",
    "self": "https://api.carebit.co/v1/token"
  },
  "livemode": false,
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "name": "Harley Street Clinic"
  },
  "project":  … }
    "id": "ba8dcd0b-5f84-45e2-8e82-ef825ee8db00",
    "object": "project",
    "name": "Referral portal"
  },
  "scopes":  … ]
    "leads.create",
    "leads.read"
  ]
}

401

The access token is missing, invalid, expired, or revoked.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403

The project is disabled or archived, or the Organization does not have the developer_platform entitlement.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429

Too many requests.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Request

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

200 response

{
  "id": "50d3e61c-c488-42b5-850c-230f3df82fb1",
  "object": "token",
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "links":  … }
    "organization": "https://api.carebit.co/v1/organization",
    "self": "https://api.carebit.co/v1/token"
  },
  "livemode": false,
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "name": "Harley Street Clinic"
  },
  "project":  … }
    "id": "ba8dcd0b-5f84-45e2-8e82-ef825ee8db00",
    "object": "project",
    "name": "Referral portal"
  },
  "scopes":  … ]
    "leads.create",
    "leads.read"
  ]
}

401 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Prefer plain text? Append ?format=md or send Accept: text/markdown to receive this page as raw Markdown.