Skip to main content
The Karma LMS API uses JWT Bearer token authentication. Every request must include a valid access token in the Authorization header. Tokens are obtained by logging in with your credentials and must be refreshed before they expire.

​
How authentication works

1

Log in with your credentials

Send a POST request to /api/v1/auth/login with your email and password. The API returns an access_token and a refresh_token.
2

Include the token in every request

Add the Authorization header to all subsequent API requests:
Authorization: Bearer <access_token>
3

Refresh the token before it expires

Access tokens expire after 1 hour. Use the refresh_token to obtain a new access token without re-entering credentials.
4

Log out to revoke the token

Call POST /api/v1/auth/logout to invalidate the token server-side when the session ends.

​
Login

POST /api/v1/auth/login Exchange credentials for an access token and refresh token.

​
Request parameters

​
email
string
required
The user’s email address.
​
password
string
required
The user’s password. Must be at least 8 characters.

​
Response fields

​
access_token
string
required
JWT used to authenticate API requests. Include this in the Authorization: Bearer header.
​
refresh_token
string
required
Long-lived token used to obtain new access tokens. Store this securely.
​
expires_in
number
required
Number of seconds until the access token expires. Typically 3600 (1 hour).
​
token_type
string
required
Always "Bearer".

​
Example

curl -X POST https://your-domain.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }'

​
Refresh token

POST /api/v1/auth/refresh Obtain a new access token using a valid refresh token. The response includes a new access_token and resets the expiry. The refresh token itself is rotated on each use.
​
refresh_token
string
required
A valid refresh token obtained from the login response.
curl -X POST https://your-domain.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4gdmFsdWU"}'

​
Logout

POST /api/v1/auth/logout Revokes the current access token and its associated refresh token server-side. After logout, both tokens are immediately invalid. 
curl -X POST https://your-domain.com/api/v1/auth/logout \
  -H "Authorization: Bearer <access_token>"
Calling /auth/logout immediately invalidates both the access token and the refresh token. Any in-flight requests using the revoked token will receive a 401 Unauthorized response.

​
Token expiry

Token typeLifetime
Access token1 hour
Refresh token7 days
Refresh tokens are single-use and rotated on every refresh call. If a refresh token is used more than once (e.g., due to a replay attack), both tokens are revoked immediately.

​
Security considerations

For security-sensitive applications, store tokens in memory or a secure HTTP-only cookie rather than localStorage. Tokens stored in localStorage are accessible to any JavaScript on the page, making them vulnerable to XSS attacks.
Implement proactive token refresh in your client. Check expires_in after login and schedule a refresh request 5 minutes before expiry to avoid authentication interruptions.

Build docs developers (and LLMs) love

Get started for freeTalk to us