Authentication
On this page
Purpose
Every API request is authenticated as an organization. API keys are the usual credential. OAuth 2.0 client-credentials tokens are the other.
API keys
Send the key in X-API-Key, or in the Authorization header with the ApiKey scheme:
X-API-Key: bk_user_<64 hex characters>
Authorization: ApiKey bk_user_<64 hex characters>
Keys use the prefix bk_user_ in both production and sandbox. A bk_user_ key sent as Authorization: Bearer is rejected.
There are no token scopes. A key belongs to one organization and one environment (production or sandbox; new keys default to sandbox). A request with no Billyou-Version header resolves to 2026-08-01, not a version stored on the key. See Versioning. By default, every API key of the organization shares one limit of 60 requests per minute. Billyou can set a different limit, and partner routes use their own threshold. See Rate limits.
Create, rotate, and delete keys in the Developer Portal, on the API Keys page. The Billyou app links there as Portal Dezvoltatori for accounts with the hasapi flag. Keys are not created under Settings → API & Integrations.
Expiry is optional (expiresInDays, default never). You can rotate a key (POST the key's rotate action) or delete it. An organization can have at most 25 keys.
Bearer tokens
Authorization: Bearer is accepted only for:
- a Kinde session JWT
- an OAuth client-credentials access token, prefix
bk_at_
Obtain an access token from POST /api/oauth/token with grant_type=client_credentials. The public walkthrough is OAuth 2.0 client credentials. Tokens last one hour, use the prefix bk_at_, and have the same access as an API key. OAuth does not add scopes. Clients are managed in the Developer Portal under OAuth Clients (at most 25 active clients per organization). The client_secret is shown once.
Errors
A missing or rejected credential returns HTTP 401:
{ "success": false, "errorCode": "UNAUTHORIZED", "message": "..." }
There is no insufficient_scope error. See Errors and Rate limits.