---
title: "Authentication"
description: "Authenticate client storefront requests and pass learner and organisation context safely."
source: "https://docs.blend-ed.com/blendx-discovery/authentication/"
---

# 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.