Respondeo
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_here

Examples

cURL

curl -H "x-api-key: your_api_key_here" \
  https://respondeo.example.com/api/quizzes

JavaScript (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

ScopeDescription
quizzes:readList and view quizzes, leaderboards
quizzes:writeCreate, update, delete quizzes
attempts:readView quiz attempts
attempts:writeSubmit 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

  1. Never expose API keys in client-side code or version control
  2. Use HTTPS in production to encrypt API keys in transit
  3. Rotate keys regularly by deleting old keys and creating new ones
  4. Set expiration dates when creating keys
  5. Monitor usage through the admin panel
  6. Use environment variables to store keys

Next Steps

On this page