Migrate authentication from v1
v2 keeps the OAuth2 client-credentials grant, so you still mint a token with a client id and client secret. A v1 key that shows an API v1 badge in the dashboard works on v2 with the same client id and secret; you can also create a key there. The token endpoint, the request body and the response change, and the token request has its own rate limit per client_id.
The token request
An integration that calls POST /v1/auth before every request breaks on v2. POST /v2/oauth/token allows a burst of 20 requests per client_id, then one every 10 seconds; the 21st returns 429 with Retry-After.
Mint one token per key, cache it, and reuse it until expires_at = now + expires_in - 300. Re-mint once on a 401, then retry the request once. On a 429 from POST /v2/oauth/token, wait Retry-After seconds. For a token manager in code, see Mint one access token and reuse it.
v1 takes only client_id and client_secret. On v2, you also send grant_type and audience in the JSON body:
- POST https://<your v1 host>/v1/auth
+ POST https://api.brellium.com/v2/oauth/token
Content-Type: application/json
{
+ "grant_type": "client_credentials",
"client_id": "$BRELLIUM_CLIENT_ID",
"client_secret": "$BRELLIUM_CLIENT_SECRET",
+ "audience": "https://api.brellium.dev"
}
v1 returns only access_token; v2 returns access_token, token_type, expires_in and scope. expires_in is in seconds (about a day), so read it from every response instead of hardcoding it.
A wrong client_secret or an unknown client_id returns 401 with an access_denied body in the OAuth error format, outside the v2 error envelope and without request_id. A 502 BAD_GATEWAY means the token endpoint is temporarily unavailable; your cached token keeps working, so retry the token request with backoff. For keys and every token failure, see Authenticate with OAuth2 client credentials.
Health check and electronic health record (EHR) ids
| v1 | v2 | What changes |
|---|---|---|
GET /v1/ |
GET /health |
It needs no token and returns {"status": "ok"}. |
POST /v1/ehr-ids |
no v2 equivalent | Contact Brellium support before you stop calling it on v1. |
Next
Mint one access token and reuse it
Mint a token once, cache it until expires_in, re-mint on 401, wait on 429.
Migrate list calls from v1
Replace v1 page and pageSize lists with v2 cursor pagination.
