Authentication

All API requests require an API key. Organization admins can create and manage API keys on terminal.mccoy.org. API keys provide tenant-scoped access to courses, learner lookup, plan-based provisioning, Surface embed links, and student progress reporting.

Using Your API Key

Include your API key in the X-Api-Key header:

curl -X GET "https://api.mccoy.org/api/v1/courses" \
  -H "X-Api-Key: ak-xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

API Key Format

API keys follow this format:

ak-{8-char-prefix}_{32-char-secret}

Example: ak-a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2

Keep Your Key Secret

Store your API key securely. If compromised, ask your organization admin to rotate or revoke the key on terminal.mccoy.org.

Permissions

Your API key has permissions that control which endpoints can be accessed:

Permission	Description
`read_courses`	List and view courses
`read_topics`	List and view topics within courses
`read_progress`	Read student progress data
`read_learners`	List existing learners and find public `learner_id` values
`manage_plans`	Create and manage learner plans
`provision_learners`	Create/update learner identities and assign or revoke plans
`create_surface_embed_links`	Create short-lived Surface embed links for existing McCoy learners

Tenant Scope

Each API key belongs to one tenant. Course access, plans, provisioned learners, and learner progress records are scoped to that tenant. Integrations do not need to send a tenant header with /api/v1 requests; use the API key for the tenant you want to operate on.

Rate Limits

Each API key has rate limits:

Per minute: Default 60 requests/minute
Per hour: Default 1,000 requests/hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1705312245

Authentication Errors

Error Code	HTTP Status	Description
`UNAUTHORIZED`	401	No authentication provided or invalid credentials
`INVALID_API_KEY`	401	API key is invalid, expired, or deactivated
`ORG_REQUIRED`	403	Organization context required for this operation
`TENANT_REQUIRED`	403	API key is not scoped to a tenant
`FEATURE_NOT_ENTITLED`	403	The requested capability is not enabled for this organization
`INSUFFICIENT_PERMISSIONS`	403	API key lacks required permission

Example error response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No authentication provided"
  }
}

Getting an API Key

Ask your organization admin to create an API key on terminal.mccoy.org. Your admin controls the key name, permissions, rate limits, and revocation.