Authentication
The API accepts two credentials: organization API tokens (lh_…) for servers, and user session JWTs for acting as a person. Which one an endpoint takes is fixed per group.
Two kinds of credentials
Both are sent the same way, as a bearer token in the Authorization header. The API tells them apart by prefix: a value starting with lh_ is an API token, anything else is read as a user JWT.
| API token | User session (JWT) | |
|---|---|---|
| Looks like | lh_… | eyJhbGciOi… |
| Acts as | The organization, capped by its creator's role | One signed-in user |
| Get one from | Dashboard → Developers → API Access | POST /api/v1/auth/login (or the browser cookie) |
| Lifetime | Until revoked, or an optional expiry date | 8 hours, renewable with the refresh token |
| Use it for | Servers, scripts, headless sites, sync jobs | Acting on behalf of a person; session-only endpoints |
API tokens
Create tokens in the dashboard under Developers → API Access. The full value is shown once; LearnHouse keeps only a hash and the first 12 characters. A token belongs to one organization. On LearnHouse Cloud tokens need the Pro plan or higher; every self-hosted instance has them.
curl "https://api.learnhouse.io/api/v1/courses/org_slug/your-school/page/1/limit/10" \
-H "Authorization: Bearer lh_YOUR_API_TOKEN"import { createClient } from "@learnhouse/sdk";
const lh = createClient({
baseUrl: "https://api.learnhouse.io",
token: process.env.LEARNHOUSE_TOKEN, // "lh_…"
});A token stops working when it is revoked or regenerated, when its expiry date passes, when its creator leaves the organization, or (on Cloud) when the organization drops below Pro. Tokens cannot manage other tokens: the API Tokens endpoints are session-only. Creating and regenerating tokens is limited to 10 per hour per IP.
Token rights
Each token carries Create, Read, Update and Delete rights per resource. The right an endpoint needs follows its HTTP method: GET needs Read, POST Create, PUT/PATCH Update and DELETE Delete. Every endpoint page shows the exact right, for example courses:read. A token missing it gets 403 with API token does not have 'read' permission for courses.
| Dashboard resource | Right key | Endpoints |
|---|---|---|
| User Groups | usergroups | User Groups · 12 |
| Courses | courses | Courses · 30 |
| Chapters | coursechapters | Chapters · 10 |
| Activities | activities | Activities · 27 |
| Assignments | assignments | Assignments · 33 |
| Folders | folders | Folders · 15 |
| Media | media | Media · 8 |
| Certifications | certifications | Certifications · 8 |
| Payments | payments | Payments · 58 |
| Search | search | Search · 1 |
A token can never do more than the user who created it: its rights are re-checked against the creator's current role on every request.
User sessions
Sign in with form-encoded username (the email) and password. The response carries an access token valid for 8 hours and a refresh token. Browsers also receive them as HttpOnly cookies (LH_access, LH_refresh), and the API reads the cookie when no Authorization header is sent.
curl -X POST "https://api.learnhouse.io/api/v1/auth/login" \
--data-urlencode 'username=ada@example.com' \
--data-urlencode 'password=a-strong-password'{
"user": {
"id": 1,
"email": "ada@example.com",
"username": "ada"
},
"tokens": {
"access_token": "eyJhbGciOi…",
"refresh_token": "eyJhbGciOi…",
"expiry": 1767225600000
}
}If the account uses two-factor authentication the login answers { "mfa_required": true, "mfa_token": "…" } instead; finish with POST /api/v1/auth/login/mfa. Logins are limited to 30 attempts per 5 minutes per IP. Then send the access token as the bearer:
curl "https://api.learnhouse.io/api/v1/users/profile" \
-H "Authorization: Bearer YOUR_JWT"All sign-in, refresh, logout and MFA endpoints are in Authentication endpoints. For the full walkthrough see the authentication guide.
Access by group
Session-only groups answer an API token with 403 and API tokens cannot access this resource. Only user authentication is allowed. Within Assignments, the learner-side /me and submission endpoints are also session-only.
| Group | Accepts | Endpoints |
|---|---|---|
| Authentication | Credentials / session | 20 |
| API Tokens | Session only | 6 |
| Organizations | Session only | 59 |
| Users | Session only | 22 |
| User Groups | API token or session | 12 |
| Courses | API token or session | 30 |
| Chapters | API token or session | 10 |
| Activities | API token or session | 27 |
| Blocks | Session only | 8 |
| Assignments | API token or session | 33 |
| Folders | API token or session | 15 |
| Media | API token or session | 8 |
| Certifications | API token or session | 8 |
| Payments | API token or session | 58 |
| Search | API token or session | 1 |
| Analytics | Session only | 13 |
| Webhooks | Session only | 9 |
| Headless | API token only | 37 |
Session only: API Tokens, Organizations, Users, Blocks, Analytics, Webhooks.