API Reference¶

Complete reference for the Coaching App REST API.

Base URL¶

Environment	URL
Development	`http://localhost:3001`
Production	Configured via `BETTER_AUTH_URL` environment variable

All routes are prefixed with /api.

Required Headers¶

Every request from any client (web, iOS, Android) must include two headers.

X-Client-Key¶

Identifies the first-party client. Validated before any route or user authentication runs.

X-Client-Key: cak_<your_key>

Configured via CLIENT_API_KEY environment variable on the backend.
The frontend reads it from EXPO_PUBLIC_CLIENT_KEY and injects it automatically.
Missing or incorrect keys receive 403 Forbidden with no further detail.
OPTIONS (CORS preflight) requests are exempt.
The server refuses to start if CLIENT_API_KEY is absent or shorter than 32 characters.

Generating a new key:

node -e "
const c = require('crypto');
const A = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
let n = BigInt('0x' + c.randomBytes(32).toString('hex')), e = '';
while (n > 0n) { e = A[Number(n % 58n)] + e; n /= 58n; }
console.log('cak_' + e);
"

Set the same value in both backend/.env (CLIENT_API_KEY) and frontend/.env (EXPO_PUBLIC_CLIENT_KEY).

X-Organization-Id¶

Required for all org-scoped endpoints to identify the active organization context.

X-Organization-Id: <organization-uuid>

If omitted, the backend falls back to profiles.currentOrganizationId from the session.
Set automatically by the frontend API client when the user has a current org selected.

Authentication¶

Authentication is session-based via Better-auth. A better-auth.session_token cookie is set on sign-in and must be present for all authenticated requests.

See the Authentication reference for detailed endpoint documentation.

Pagination¶

List endpoints support limit and offset query parameters.

Parameter	Type	Default	Max	Description
`limit`	integer	50–100 (varies)	200–1000 (varies)	Number of records to return
`offset`	integer	`0`	—	Number of records to skip

Response envelope for paginated lists:

{
  "data": [ ... ],
  "meta": {
    "total_count": 142
  }
}

Response Format¶

Success¶

Single resource:

{
  "data": { ... }
}

List:

{
  "data": [ ... ],
  "meta": {
    "total_count": 42
  }
}

Simple acknowledgement:

{
  "success": true
}

Errors¶

{
  "error": "Description of what went wrong"
}

Common HTTP status codes:

Code	Meaning
`400`	Bad request — invalid input or missing required field
`401`	Unauthenticated — missing or expired session
`403`	Forbidden — authenticated but insufficient role
`404`	Resource not found
`409`	Conflict — resource already exists
`413`	Payload too large
`422`	Unprocessable — business rule violation
`500`	Internal server error

Role Hierarchy¶

Access control is enforced on every endpoint. Roles from highest to lowest:

Role	Scope	Level
`Owner`	Global	15
`PlatformAdmin`	Global	10
`OrganizationAdmin`	Org	3
`Manager`	Org	2
`Coach`	Org	1
`Teacher`	Org	1

Global roles (Owner, PlatformAdmin) are stored in user.globalRole. Org roles are stored in organizationUsers.roleInOrganization. A user with a global role is not included in org-scoped lists.

Sections¶

Section	Base Path	Description
Authentication	`/api/auth/*`	Sign-up, sign-in, sign-out, password reset
Me	`/api/me/*`	Current user profile and organizations
Users	`/api/users/*`	User management
Organizations	`/api/organizations/*`	Org management, members, invites
Mentorships	`/api/mentorships/*`	Coach-teacher relationships
Sessions	`/api/sessions/*`	Video session scheduling and management
Files	`/api/files/*`	File upload, attachment, and retrieval
Events	`/api/events/*`	Server-Sent Events stream
System	`/api/health`	Operational health and env diagnostics
Setup	`/api/setup/*`	Initial platform bootstrap