Authentication
The API uses API keys for server-to-server authentication. Each key is scoped to a single company (coaching business) and acts through a coach in that company, subject to role and resource checks and the API-key restrictions below.
Creating an API key
- Open the TrainerStudio coach app.
- Go to Settings → API Keys.
- Click Create API Key and give it a descriptive name (e.g. "Zapier integration", "Claude agent").
- Copy the key and store it securely. You can reveal it again from Settings → API Keys.
Using the key
Send the key in the X-API-Key header on every request:
curl "https://api.trainerstudio.io/coach/customers?archived=false&pageSize=20&pageNum=1" \
-H "X-API-Key: YOUR_API_KEY"Send only X-API-Key for API-key authentication. If you also send an
Authorization header, the bearer session takes precedence. The customers
list requires archived, pageSize and pageNum; they have no defaults.
Key properties
| Property | Detail |
|---|---|
| Scope | Company-level. Access is evaluated as a coach in the company, subject to endpoint permissions and API-key restrictions. |
| Format | Opaque string. Treat it as a secret. |
| Storage | The server stores the key encrypted at rest. You can re-read it from Settings → API Keys, so treat that screen as sensitive. |
| Revocation | Instant. Go to Settings → API Keys → Delete. |
What an API key cannot do
Some operations are deliberately restricted to an interactive session in the
coach app and answer 403 when called with X-API-Key alone:
- Creating, listing, revealing or revoking API keys.
- Impersonating a client, or changing a client's password.
- Managing team members (employees) and their permissions.
- Deleting the coach account.
Error responses
| Status | Meaning |
|---|---|
401 Unauthorized | Missing or invalid X-API-Key header. |
403 Forbidden | The operation is restricted for API keys, or the authenticated coach lacks permission. |
{
"message": "Invalid API key"
}The example above is an invalid-key response. A missing credential on a
protected REST endpoint returns 401 with {"statusCode":401,"message":"Unauthorized"}.
Error envelopes vary by endpoint; always check the HTTP status and message.
Security best practices
- Never expose keys in client-side code — API keys are for server-to-server use only.
- Use one key per integration so you can revoke individually without breaking other systems.
- Store keys in environment variables or a secrets manager, never in source code.
- Rotate keys periodically — create a new one, update your integration, then revoke the old one.