Authentication
Credential model, token refresh flow, and security guidance for the Cobru API.
Cobru uses a layered authentication model:
x-api-key: your integration keyAuthorization: Bearer {access}: a short-lived access token from/token/refresh/
Start here
- Store
x-api-keyand therefreshtoken only in backend secret storage. - Mint an access token from
/token/refresh/. - Cache the access token centrally before making routine API calls.
- Reuse the token until refresh is needed instead of minting on every request.
Credential roles
| Credential | Where to use it | Notes |
|---|---|---|
x-api-key | backend requests | Treat it as an integration credential and keep it out of frontend bundles |
refresh token | backend secret storage only | Used only to mint short-lived access tokens |
access token | backend requests | Cache aggressively, rotate often |
Token refresh flow
curl -X POST https://dev.cobru.co/token/refresh/ \
-H "x-api-key: $COBRU_API_KEY" \
-H "Content-Type: application/json" \
-d '{"refresh":"'"$COBRU_REFRESH_TOKEN"'"}'Expected response
{ "access": "eyJ0eXAi..." }The body field is refresh, not refresh_token. This discrepancy is one of the most important Cobru quirks to document internally.
Required headers for API requests
x-api-key: {your_api_key}
Authorization: Bearer {access}
Accept: application/json
Content-Type: application/jsonToken lifetime and caching
| Property | Recommendation |
|---|---|
| Observed token lifetime | about 60 minutes |
| Safe cache TTL | 50 minutes |
| Edge runtime caveat | in-memory caches do not persist between invocations |
| Production fix | keep the token in Redis, Vercel KV, or another shared cache |
Environment variables
COBRU_BASE_URL=https://dev.cobru.co
COBRU_API_KEY=...
COBRU_REFRESH_TOKEN=...Security checklist
- Keep all Cobru credentials in server-side environment variables only.
- Never send
x-api-keyto browsers or mobile clients. - Refresh the access token from the server, not from the frontend.
- Rotate credentials when team membership changes.
- Use HTTPS-only callback URLs in production.
Read next
/docs/getting-started/docs/webhooks/docs/api/authentication/refresh