Authentication

Every client-facing route in this guide requires an accepted identity. A request without one receives 401.

Choose the correct credential

Credential	Intended caller	Where it is accepted
Session cookie, JWT, or OAuth2 bearer token	Signed-in learner or staff client	User-facing routes, subject to each route’s permissions.
clientapisecret	Trusted storefront backend, CRM, or partner service	/blendxapi/discovery/, /blendxapi/enrollments/client/, and /blendxapi/banner/list/.

An authenticated user can read most catalog endpoints without a client secret. Machine storefront calls use:

clientapisecret: <CLIENT_API_SECRET>

The configured value is compared in constant time and fails closed when it is empty. The credential is instance-wide and is not scoped to one organisation, course, or learner.

Do not expose the client secret

Keep CLIENT_API_SECRET in the storefront server or integration platform. Never send it to browser JavaScript, a mobile client, or a third-party user.

Browser and server-side storefront calls

Use a backend-for-frontend pattern:

1. The browser calls your storefront server.
2. Your server validates the public request and applies its own abuse controls.
3. Your server calls the LMS with clientapisecret.
4. Your server returns only the required response data.

Forward a signed-in user’s session cookies only to endpoints that need learner identity. The authenticated discovery checkout requires both the client secret and the user’s LMS session.

Organisation context

Organisation-scoped learner and payment routes resolve the tenant from one of:

Cookie: orgName=acme

or, for the native mobile client:

orgName: acme

The value selects a tenant; it is not proof of access. Protected endpoints join it with the authenticated user’s organisation claims. Web integrations should prefer the cookie channel used by the learner web application.

Catalog list and detail endpoints can span multiple organisations. Their regional pricing is resolved independently for each item’s owning organisation.

Common authentication failures

Status	Cause	Action
401	Missing or invalid user identity or machine credential.	Check the exact header name and configured secret.
403	The user is authenticated but lacks access to the selected organisation or operation.	Check organisation membership and role permissions.
400 Organisation not found	An organisation-scoped route cannot resolve orgName.	Set the expected tenant cookie or header.

Do not retry 401 or 403 responses without changing credentials or access.