API Tokens - LearnHouse

Overview

API tokens provide secure, programmatic access to the LearnHouse API. They are ideal for:

Integrations with third-party services
CI/CD pipelines
Automated scripts and tools
Server-to-server communication

Token Features

Organization Scoped

Each token is scoped to a specific organization

Configurable Rights

Fine-grained permission control

Optional Expiration

Set expiration dates or create permanent tokens

Usage Tracking

Monitor last usage timestamp

Token Format

API tokens use a prefix-based format for easy identification:

Prefix: lh_ (first 12 characters visible)
Full token shown only once upon creation
Stored as SHA-256 hash in database

Security: The full token value is only shown once upon creation. Store it securely immediately. You cannot retrieve it later.

Create API Token

endpoint

string

POST /api/v1/orgs/{org_id}/api-tokens

Path Parameters

org_id

integer

required

Organization ID for the token scope

Request Body

name

string

required

Token name (max 100 characters)

description

string

Token description (max 500 characters)

rights

object

Permission rights for the token (follows organization rights structure)

expires_at

string

ISO 8601 timestamp for token expiration (null = never expires)

Response

token

string

Full API token - Only shown once! Store securely.

token_uuid

string

Unique token identifier (format: apitoken_{uuid})

name

string

Token name

description

string

Token description

token_prefix

string

First 12 characters of the token (e.g., “lh_abc12345”)

org_id

integer

Organization ID

rights

object

Token permissions

created_by_user_id

integer

ID of user who created the token

creation_date

string

ISO timestamp of creation

expires_at

string

ISO timestamp of expiration

Example

curl -X POST https://api.learnhouse.app/api/v1/orgs/123/api-tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "name": "CI/CD Pipeline",
    "description": "Token for automated deployments",
    "rights": {
      "courses": {
        "action_read": true,
        "action_create": false
      }
    },
    "expires_at": "2027-12-31T23:59:59Z"
  }'

List API Tokens

endpoint

string

GET /api/v1/orgs/{org_id}/api-tokens

Returns all API tokens for an organization (without the full token secret).

Path Parameters

org_id

integer

required

Organization ID

Response

Array of token objects (without the token field):

integer

Token database ID

token_uuid

string

Token UUID

name

string

Token name

token_prefix

string

Token prefix (first 12 characters)

is_active

boolean

Whether token is active (false if revoked)

last_used_at

string

ISO timestamp of last usage

expires_at

string

ISO timestamp of expiration

Example

curl -X GET https://api.learnhouse.app/api/v1/orgs/123/api-tokens \
  -H "Authorization: Bearer <your_access_token>"

Get API Token

endpoint

string

GET /api/v1/orgs/{org_id}/api-tokens/{token_uuid}

Get details of a specific API token.

Path Parameters

org_id

integer

required

Organization ID

token_uuid

string

required

Token UUID (format: apitoken_{uuid})

Example

curl -X GET https://api.learnhouse.app/api/v1/orgs/123/api-tokens/apitoken_abc123 \
  -H "Authorization: Bearer <your_access_token>"

Update API Token

endpoint

string

PUT /api/v1/orgs/{org_id}/api-tokens/{token_uuid}

Update token name, description, rights, or expiration. Cannot change the token secret (use regenerate for that).

Path Parameters

org_id

integer

required

Organization ID

token_uuid

string

required

Token UUID

Request Body

All fields are optional:

name

string

New token name

description

string

New token description

rights

object

Updated permissions

expires_at

string

New expiration timestamp

Example

curl -X PUT https://api.learnhouse.app/api/v1/orgs/123/api-tokens/apitoken_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "name": "Updated Token Name",
    "description": "New description"
  }'

Regenerate API Token

endpoint

string

POST /api/v1/orgs/{org_id}/api-tokens/{token_uuid}/regenerate

Generate a new token secret. The old token immediately stops working.

Breaking Change: The old token is immediately revoked. Update all systems using the old token.

Path Parameters

org_id

integer

required

Organization ID

token_uuid

string

required

Token UUID

Response

Returns the same response as creating a new token, including the new full token value.

Example

curl -X POST https://api.learnhouse.app/api/v1/orgs/123/api-tokens/apitoken_abc123/regenerate \
  -H "Authorization: Bearer <your_access_token>"

Revoke API Token

endpoint

string

DELETE /api/v1/orgs/{org_id}/api-tokens/{token_uuid}

Revoke an API token. The token immediately stops working. This action cannot be undone.

Path Parameters

org_id

integer

required

Organization ID

token_uuid

string

required

Token UUID

Response

{
  "message": "Token revoked successfully"
}

Example

curl -X DELETE https://api.learnhouse.app/api/v1/orgs/123/api-tokens/apitoken_abc123 \
  -H "Authorization: Bearer <your_access_token>"

Using API Tokens

Include the API token in the Authorization header as a Bearer token:

curl -X GET https://api.learnhouse.app/api/v1/orgs/123/courses \
  -H "Authorization: Bearer lh_your_api_token_here"

Token Scope

API tokens can only access resources within their organization scope:

✅ Can access: /api/v1/orgs/123/courses (same org)
❌ Cannot access: /api/v1/orgs/456/courses (different org)

Rate Limiting

Token creation and regeneration are rate-limited to prevent abuse:

429 Too Many Requests

error

{
  "detail": "Too many token creation requests. Try again in 60 seconds."
}

Permissions Required

API token management requires specific organization permissions:

Create: roles.action_create permission
List/Get: roles.action_read permission
Update/Regenerate: roles.action_update permission
Revoke: roles.action_delete permission

Security Best Practices

Store Tokens Securely

Never commit tokens to version control
Use environment variables or secret management systems
Encrypt tokens at rest
Limit access to token storage

Use Minimal Permissions

Grant only necessary rights to each token
Create separate tokens for different purposes
Review and update rights regularly

Set Expiration Dates

Use expiration dates for temporary integrations
Rotate tokens periodically
Monitor expiring tokens

Monitor Usage

Track last_used_at timestamps
Revoke unused tokens
Audit token activity regularly

Rotate Compromised Tokens

Immediately revoke compromised tokens
Use regenerate endpoint to rotate secrets
Investigate unauthorized usage

Error Codes

400 Bad Request

error

Invalid input (name too long, invalid rights structure, etc.)

401 Unauthorized

error

Missing or invalid authentication

403 Forbidden

error

Insufficient permissions for the operation

404 Not Found

error

Token or organization not found

429 Too Many Requests

error

Rate limit exceeded for token creation/regeneration

Authentication Overview

Learn about authentication methods

Permissions

Understand the rights system

Authentication

Core Resources

Content

AI & Advanced

​Overview

​Token Features

Organization Scoped

Configurable Rights

Optional Expiration

Usage Tracking

​Token Format

​Create API Token

​Path Parameters

​Request Body

​Response

​Example

​List API Tokens

​Path Parameters

​Response

​Example

​Get API Token

​Path Parameters

​Example

​Update API Token

​Path Parameters

​Request Body

​Example

​Regenerate API Token

​Path Parameters

​Response

​Example

​Revoke API Token

​Path Parameters

​Response

​Example

​Using API Tokens

​Token Scope

​Rate Limiting

​Permissions Required

​Security Best Practices

​Error Codes

​Related Resources

Authentication Overview

Permissions

Build docs developers (and LLMs) love

Overview

Token Features

Token Format

Create API Token

Path Parameters

Request Body

Response

Example

List API Tokens

Path Parameters

Response

Example

Get API Token

Path Parameters

Example

Update API Token

Path Parameters

Request Body

Example

Regenerate API Token

Path Parameters

Response

Example

Revoke API Token

Path Parameters

Response

Example

Using API Tokens

Token Scope

Rate Limiting

Permissions Required

Security Best Practices

Error Codes

Related Resources