BBaalvion Help

Authentication

Every API request must be authenticated with either an API key or a short-lived access token.

API Keys

API keys are generated per organization from your dashboard’s developer settings and are scoped to the role and permissions of the account that created them. Send the key as a bearer token on every request:

Authenticated request
curl https://api.baalvion.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY"

Token-Based Auth

For integrations acting on behalf of a signed-in user (rather than a static server-to-server key), the API supports short-lived OAuth 2.0 access tokens obtained via an authorization code flow. Access tokens are sent the same way as API keys, in the Authorization header, and expire after 1 hour — use the accompanying refresh token to obtain a new one without re-prompting the user.

Refreshing a token
curl -X POST https://api.baalvion.com/v1/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

Choosing an Approach

  • API keys — server-to-server integrations you fully control (ERP sync, internal tooling).
  • OAuth tokens — third-party apps acting on behalf of individual Baalvion users.
Never expose keys client-side
API keys carry the full permissions of the account that created them. Never embed a key in frontend JavaScript, a mobile app binary, or a public repository — always call the API from a server you control.

Key Security

  • Rotate keys periodically and immediately after any suspected exposure.
  • Use separate keys per integration so a compromised key can be revoked without affecting others.
  • Store keys in a secrets manager or environment variables — never in source control.

See Error Handling for the response you’ll get on an invalid or expired credential.

PreviousAPI OverviewNextUsers API