API Reference
API Authentication
Authenticating API requests
All Respondeo API endpoints require authentication via API key.
API Key Header
Include your API key in the x-api-key header with every request:
x-api-key: your_api_key_hereExamples
cURL
curl -H "x-api-key: your_api_key_here" \
https://respondeo.example.com/api/quizzesJavaScript (Fetch)
const response = await fetch("https://respondeo.example.com/api/quizzes", {
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
});
const data = await response.json();JavaScript (Axios)
import axios from "axios";
const response = await axios.get("https://respondeo.example.com/api/quizzes", {
headers: {
"x-api-key": "your_api_key_here",
},
});
const data = response.data;Python (Requests)
import requests
headers = {
'x-api-key': 'your_api_key_here',
'Content-Type': 'application/json'
}
response = requests.get('https://respondeo.example.com/api/quizzes', headers=headers)
data = response.json()Python (httpx)
import httpx
async with httpx.AsyncClient() as client:
response = await client.get(
'https://respondeo.example.com/api/quizzes',
headers={'x-api-key': 'your_api_key_here'}
)
data = response.json()Creating API Keys
API keys must be created through the web interface by an administrator. See API Keys Guide for details.
Permissions
API keys inherit permissions from the associated user's role. The effective permissions are determined dynamically at request time.
Available Scopes
| Scope | Description |
|---|---|
quizzes:read | List and view quizzes, leaderboards |
quizzes:write | Create, update, delete quizzes |
attempts:read | View quiz attempts |
attempts:write | Submit quiz attempts |
See RBAC Guide for role and permission configuration.
Error Responses
Missing API Key
Status: 401 Unauthorized
{
"error": "API key is required"
}Invalid API Key
Status: 401 Unauthorized
{
"error": "Invalid API key"
}Insufficient Permissions
Status: 403 Forbidden
{
"error": "Insufficient permissions"
}Rate Limit Exceeded
Status: 429 Too Many Requests
{
"error": "Rate limit exceeded. Please try again later."
}Security Best Practices
- Never expose API keys in client-side code or version control
- Use HTTPS in production to encrypt API keys in transit
- Rotate keys regularly by deleting old keys and creating new ones
- Set expiration dates when creating keys
- Monitor usage through the admin panel
- Use environment variables to store keys
Next Steps
- Endpoints — Explore available endpoints
- API Keys Guide — Manage your API keys
- Error Handling — Handle errors gracefully