Authentication

You need a client_id and client_secret to interact with the Cobalt API. You will also need an access_token for each user which can be obtained in through the Cobalt Link flow.

Headers

Header	Description
`client_id`	Your Cobalt API client id
`client_secret`	Your Cobalt API secret
`access_token`	The access token for the individual provider obtained during the Link flow

Example Request

curl -X GET https://api.usecobalt.com/v1/appointments \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH'

Access Tokens

Access tokens are obtained through the Cobalt Link flow. Each access token is associated with a specific set of EHR credentials. An access token alone cannot be used against the API — every request also requires your client_id and client_secret.

Error Responses

Every authenticated endpoint runs the same credential check before your request reaches the resource. The check can fail with the following status codes:

Status	`error`	When it happens
`400`	—	One or more of `client_id`, `client_secret`, or `access_token` is missing from the request headers.
`401`	—	The `client_id` / `client_secret` / `access_token` combination does not match an active credential — a mistyped, unknown, or rotated-out token.
`403`	`login_required`	The access token is valid but the linked EHR account needs attention (deactivated, or its credentials need to be re-established). The user must reconnect through the Cobalt Link flow.
`403`	`pre_live_read_only`	A pre-live (test) access token was used on a write request. Test tokens are read-only — click Go Live in your dashboard to receive production credentials.
`403`	—	Your client is locked. Every token and EHR session under the client is invalidated. Contact support to unlock.

All error responses share the shape { "success": false, "message": "...", "error": "..." }, where error is present on the codes noted above. A GET request made with a token whose linked account needs attention (credentials_required, mfa_required, or dual_credentials_required) still succeeds so cached data stays readable, but the response carries a Cobalt-Link-Action-Required: true header and a Cobalt-Link-Access-Token-Status header describing the condition. Write requests in the same state return 403.

Rotating and Revoking Access Tokens

If a token may have been exposed, rotate it: a new token is returned and the old one is invalidated immediately. The user’s EHR connection is unaffected and no re-link is required. Requests with a rotated-out token return 401. To rotate many tokens at once, loop the rotate endpoint over your stored tokens. To revoke a user’s access entirely, deactivate the account. Subsequent requests with that token return 403 with "error": "login_required", and the user reconnects through the normal Cobalt Link flow. For a broad compromise, lock your client: every token and EHR session under your client is invalidated immediately and your client_secret is cleared. Contact support to unlock.

Introduction

Guides

Authentication

Authentication

Headers

Example Request

Access Tokens

Error Responses

Rotating and Revoking Access Tokens

​Authentication

​Headers

​Example Request

​Access Tokens

​Error Responses

​Rotating and Revoking Access Tokens

Authentication

Headers

Example Request

Access Tokens

Error Responses

Rotating and Revoking Access Tokens