Authentication

All Teacharium public API endpoints require authentication using API tokens. Tokens are organization-specific and allow secure access to your organization’s data.

API Token Format

API tokens consist of two parts separated by a period (.):

tapub_xxxxx.tasec_xxxxx

• Public Key: Begins with tapub_ and is used to identify the token
• Secret Key: Begins with tasec_ and is used to verify the token

Both parts must be included when making API requests.

Using API Tokens

Include your API token in the Authorization header using the Bearer authentication scheme:

Authorization: Bearer tapub_xxxxx.tasec_xxxxx

Example Request

curl -X GET 'https://your-domain.com/api/public/lessons' \
  -H 'Authorization: Bearer tapub_xxxxx.tasec_xxxxx'

JavaScript/TypeScript Example

const response = await fetch('https://your-domain.com/api/public/lessons', {
  headers: {
    'Authorization': `Bearer ${publicKey}.${secretKey}`
  }
});

Python Example

import requests
 
headers = {
    'Authorization': f'Bearer {public_key}.{secret_key}'
}
 
response = requests.get(
    'https://your-domain.com/api/public/lessons',
    headers=headers
)

Creating API Tokens

Only organization administrators can create API tokens. To create a token:

1. Navigate to your organization settings
2. Go to the API Tokens section
3. Click Create token
4. Provide a descriptive name for the token
5. Copy both the public and secret keys immediately—the secret key will only be shown once

For detailed instructions, see API Tokens.

Token Security

• Store securely: Never commit tokens to version control or expose them in client-side code
• Use environment variables: Store tokens in environment variables or secure configuration management systems
• One-time display: Secret keys are only shown once when created. If lost, you must create a new token
• Revoke when compromised: If a token is compromised, revoke it immediately from your organization settings
• Organization-scoped: Tokens are tied to a specific organization and can only access that organization’s data

Authentication Errors

401 Unauthorized

The API returns a 401 Unauthorized status when authentication fails.

Missing Authorization Header

{
  "error": "Missing authorization header"
}

Cause: The Authorization header is not included in the request.

Solution: Add the Authorization header with your Bearer token.

Invalid Token Format

{
  "error": "Authorization token must be provided as <public>.<secret>"
}

Cause: The token is not formatted correctly (missing the period separator or one of the parts).

Solution: Ensure you’re providing both the public and secret keys, separated by a period.

Invalid Token Scheme

{
  "error": "Authorization header must use the Bearer scheme"
}

Cause: The authorization scheme is not set to “Bearer”.

Solution: Ensure your header starts with Bearer followed by the token.

Invalid API Token

{
  "error": "Invalid API token"
}

Possible causes:

• The token does not exist in the system
• The secret key does not match the public key
• The token format is invalid (doesn’t start with correct prefixes)

Solution: Verify you’re using the correct token and that both parts are copied correctly.

Revoked Token

{
  "error": "API token has been revoked"
}

Cause: The token has been revoked and is no longer valid.

Solution: Create a new token from your organization settings.

500 Internal Server Error

{
  "error": "Failed to verify API token"
}

Cause: An unexpected error occurred while verifying the token.

Solution: Try again. If the problem persists, contact support.

Rate Limiting

Currently, there are no rate limits enforced on the public API. However, we recommend implementing reasonable request throttling in your applications to ensure optimal performance.

Best Practices

• Name tokens descriptively: Use clear names that indicate where and how the token will be used
• Rotate tokens regularly: Consider periodically creating new tokens and revoking old ones
• Use separate tokens for different environments: Create different tokens for development, staging, and production
• Monitor token usage: Check the “last used” timestamp in your token list to identify unused or potentially compromised tokens
• Test with invalid tokens: Ensure your application properly handles authentication errors