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 tokenUser session (JWT)
Looks likelh_…eyJhbGciOi…
Acts asThe organization, capped by its creator's roleOne signed-in user
Get one fromDashboard → Developers → API AccessPOST /api/v1/auth/login (or the browser cookie)
LifetimeUntil revoked, or an optional expiry date8 hours, renewable with the refresh token
Use it forServers, scripts, headless sites, sync jobsActing 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.

Authenticate with a token
curl "https://api.learnhouse.io/api/v1/courses/org_slug/your-school/page/1/limit/10" \
  -H "Authorization: Bearer lh_YOUR_API_TOKEN"

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 resourceRight keyEndpoints
User GroupsusergroupsUser Groups · 12
CoursescoursesCourses · 30
ChapterscoursechaptersChapters · 10
ActivitiesactivitiesActivities · 27
AssignmentsassignmentsAssignments · 33
FoldersfoldersFolders · 15
MediamediaMedia · 8
CertificationscertificationsCertifications · 8
PaymentspaymentsPayments · 58
SearchsearchSearch · 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.

Sign incURL
curl -X POST "https://api.learnhouse.io/api/v1/auth/login" \
  --data-urlencode 'username=ada@example.com' \
  --data-urlencode 'password=a-strong-password'
Response200 · JSON
{
  "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:

Call a session endpointcURL
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.

GroupAcceptsEndpoints
AuthenticationCredentials / session20
API TokensSession only6
OrganizationsSession only59
UsersSession only22
User GroupsAPI token or session12
CoursesAPI token or session30
ChaptersAPI token or session10
ActivitiesAPI token or session27
BlocksSession only8
AssignmentsAPI token or session33
FoldersAPI token or session15
MediaAPI token or session8
CertificationsAPI token or session8
PaymentsAPI token or session58
SearchAPI token or session1
AnalyticsSession only13
WebhooksSession only9
HeadlessAPI token only37

Session only: API Tokens, Organizations, Users, Blocks, Analytics, Webhooks.