Authenticate Requests to the Fayne Academy REST API

This section is for the person or service connecting another tool to your academy. If terms such as request, header, or API key are unfamiliar, create the key in Fayne and share this page with the person building the connection. All requests to the Fayne Academy REST API must include an API key. The API uses Bearer token authentication: you pass your key in the Authorization header on every request. Each key is scoped to a single academy, so the API infers your academy from the key you provide. You never pass an academy identifier separately, and the host you call does not matter because the academy comes from the key.

The REST API is available on Fayne’s paid plans. On a free or trial plan, API requests are rejected with a 402 (trial_api_unavailable). Upgrade to enable API access.

Generating an API key

Open your academy owner dashboard and navigate to Settings > API Keys. Click Create API key, give it a name, and copy the full key immediately. It is shown only once.

Store your API key in an environment variable or secrets manager. Never commit it to source control or expose it in client-side code.

Key format

Every API key begins with the prefix fa_live_ followed by 32 lowercase hexadecimal characters, making the full key 40 characters long.

fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
         └─────────── 32 hex chars ─────────┘

Sending the Authorization header

Include your key as a Bearer token in the Authorization header of every request.

Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example request

curl https://yourname.fayneos.com/api/v1/courses \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Rate limiting

Requests are rate-limited per API key. When you exceed the limit, the API returns a 429 response with a Retry-After header indicating how many seconds to wait before retrying.

Error codes

The table below covers authentication and common resource errors you may encounter across all endpoints.

HTTP status	Code	When it occurs
`401`	`unauthorized`	Missing or invalid `Authorization` header
`401`	`unauthorized`	API key does not start with `fa_live_`
`401`	`unauthorized`	API key is revoked or does not exist
`402`	`trial_api_unavailable`	API access requires a paid plan
`402`	`academy_locked`	The academy is locked (for example, billing inactive)
`402`	`limit_exceeded`	A plan limit was reached
`400`	`validation_error`	A path or body value failed validation (for example, a malformed UUID)
`400`	`invalid_course`	Only published courses can be assigned
`400`	`invalid_courses`	Some course IDs are invalid or unpublished
`400`	`invalid_lists`	Some list IDs are invalid or not in this academy
`403`	`forbidden`	The key is not permitted to perform this action
`404`	`not_found`	Student, course, or list not found in this academy
`409`	`already_exists`	The student is already a member, or a list with that name already exists
`429`	`rate_limit_exceeded`	Too many requests; check the `Retry-After` header
`500`	`internal_error`	An unexpected server error occurred

Error response shape

When a request fails, the API returns a JSON body with an error object containing a code and a human-readable message.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Common questions

Can I connect my CRM or other tools?

Yes. Use this REST API to sync people from your customer management or signup tool: call POST /api/v1/students to add a student and enroll them in courses in one request, or manage lists so course access follows list membership (add someone in your tool and they get access; remove them and it is revoked). To let an AI assistant like Claude or Cursor read and edit your course content directly, see Connect AI Tools.

Authentication

Endpoints

Guides

Authenticate Requests to the Fayne Academy REST API

Generating an API key

Key format

Sending the Authorization header

Example request

Rate limiting

Error codes

Error response shape

Common questions

​Generating an API key

​Key format

​Sending the Authorization header

​Example request

​Rate limiting

​Error codes

​Error response shape

​Common questions

Generating an API key

Key format

Sending the Authorization header

Example request

Rate limiting

Error codes

Error response shape

Common questions