Skip to main content

​
API Keys

Every request to the Quiz Quail API must be authenticated with an API key. You can create and manage keys from your dashboard settings.

​
Key Format

API keys use the prefix qk_live_ followed by 40 hex characters: 
qk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
When you create a key, the full value is shown once. After that, only the first 16 characters (the prefix) are stored for identification. Copy and store your key securely before closing the dialog.

​
Creating a Key

  1. Go to Settings > API Keys in the Quiz Quail dashboard.
  2. Click Create API Key.
  3. Give the key a descriptive name (e.g., “CI Pipeline” or “Mobile App”).
  4. Select the scopes your key needs.
  5. Copy the key immediately and store it in a secure location.

​
Revoking a Key

You can revoke a key at any time from the API Keys settings page. Revoked keys are rejected immediately on the next request. Revocation cannot be undone — you will need to create a new key.

​
Using Your API Key

Pass your API key in the Authorization header as a Bearer token. 
curl -X GET https://app.quiz-quail.com/api/v1/quizzes \
  -H "Authorization: Bearer qk_live_YOUR_API_KEY"
Never include your API key directly in client-side code, URLs, or query parameters. Always send it in the Authorization header over HTTPS.

​
Scopes

Each API key is assigned one or more scopes that control which endpoints it can access. Follow the principle of least privilege — only grant the scopes your integration actually needs.

​
Available Scopes

ScopeDescription
quizzes:readRead quizzes, rounds, and questions
quizzes:writeCreate, update, and delete quizzes
themes:readRead themes
themes:writeCreate, update, and delete themes
media:readRead and list media files
media:writeUpload and delete media files
renders:readRead render jobs and their status
renders:writeCreate and manage render jobs
youtube:readRead YouTube upload status and metadata
youtube:writeUpload videos to YouTube and manage uploads
webhooks:readRead webhook configurations
webhooks:writeCreate, update, and delete webhooks
ai:readRead AI generation history and status
ai:writeGenerate quizzes and content using AI

​
Common Scope Combinations

Use CaseRecommended Scopes
Read-only dashboardquizzes:read, themes:read, renders:read
CI/CD rendering pipelinequizzes:read, renders:read, renders:write
Full quiz managementquizzes:read, quizzes:write, themes:read, themes:write, media:read, media:write
YouTube publishingrenders:read, youtube:read, youtube:write
AI-powered quiz creationquizzes:read, quizzes:write, ai:read, ai:write

​
Error Responses

Authentication and authorization errors follow the RFC 9457 Problem Details format.

​
401 Unauthorized

Returned when no valid credentials are provided — the key is missing, malformed, or revoked. 
{
  "type": "https://quizquail.com/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication required. Provide an API key via Authorization: Bearer header, or use a valid session cookie."
}
Common causes:
  • Missing Authorization header
  • Incorrect key (typo or wrong environment)
  • Key has been revoked

​
403 Forbidden

Returned when your key is valid but does not have the required scopes for the endpoint. 
{
  "type": "https://quizquail.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient scopes. Required: quizzes:write. Your key has: quizzes:read"
}
How to fix: Create a new API key with the required scopes, or update your existing key’s scope configuration. The error detail field tells you exactly which scopes are missing versus which scopes your key has.

​
Security Best Practices

Never hard-code API keys in source code. Use environment variables or a secrets manager.
# .env (add to .gitignore!)
QUIZ_QUAIL_API_KEY=qk_live_YOUR_API_KEY

const response = await fetch("https://app.quiz-quail.com/api/v1/quizzes", {
  headers: {
    Authorization: `Bearer ${process.env.QUIZ_QUAIL_API_KEY}`,
  },
});
Grant each key only the scopes it needs. A rendering pipeline does not need quizzes:write. A read-only dashboard does not need media:write. If a key is compromised, limited scopes reduce the blast radius.
Create a new key, update your integration to use it, then revoke the old key. This limits the window of exposure if a key is leaked.
Create distinct keys for development, staging, and production. If a development key is exposed, your production data is unaffected.
API keys should only be used in server-side code. Never embed them in JavaScript bundles, mobile apps, or browser requests where they can be inspected.
Check the Last Used column in your API Keys settings to identify unused keys. Revoke any key that is no longer in active use.