Authentication
Authenticate every request with an organization API key in the X-API-Key header. Create, scope, rotate and revoke keys.
Send the key in the X-API-Key header on every request, including the first.
X-API-Key: YOUR_API_KEYcurl "https://api-next.vitruve.fit/v1/athletes" \
-H "X-API-Key: $VITRUVE_API_KEY"The key is the only credential. There are no tokens to refresh and no sessions.
The MCP server is the exception to this page: AI clients connect to it by OAuth sign-in, and API keys do not work there. See MCP server authentication.
Create and revoke keys
Keys are managed by an organization Owner in Settings → API Access (Professional plan). See Create and use Vitruve API keys for the steps in the app.
- Create one key per integration. You can then revoke one without breaking the others.
- A revoked key stops working immediately and answers
401. - To rotate a key: create the new key, deploy it, confirm traffic moved, then revoke the old one.
Plans and access
API keys work for organizations whose plan includes the API, currently Professional. The plan is checked on every request, not when the key is created:
- If the plan stops including the API, through a downgrade or a subscription that ended, every key of the organization answers
403 Your plan no longer includes API accessfrom the next request on. - The same keys work again as soon as the plan is restored. There is nothing to recreate.
Workouts, wellness questionnaires and injury reports are returned with no history limit: every plan reads them as far back as they go.
What a key can see
A key returns the data of the one organization that issued it, and nothing else. There is no way to widen that scope from a request. Ids that belong to another organization answer 404, as if they did not exist.
A key reads, and on the write endpoints writes, with the permissions the plan gives the organization's owner. Credentials, password hashes and raw encoder payloads are never returned.
Keys created under Settings → Integrations are not API keys: they belong to a partner platform and answer 401 Partner credentials required when sent alone.
Authentication errors
| Status | message | Cause |
|---|---|---|
401 | Missing X-API-Key header | The header is absent or misspelled. |
401 | Invalid API key | The value is not a known key, or it was revoked. |
401 | Organization is not active | The organization that owns the key is no longer active. |
401 | Partner credentials required | The key was created under Settings → Integrations for a partner platform. Use a key from Settings → API Access. |
403 | Your plan no longer includes API access | The organization's plan doesn't include the API, or its subscription ended. |
An address that collects 30 401 answers within a minute is answered 429 until the minute ends, so fix a failing key instead of retrying it.
Keep keys safe
- Call the API from a server you control. Do not embed a key in a web page or mobile app.
- Load it from the environment (
VITRUVE_API_KEY) or a secrets manager, not from source control. - Do not log request headers.
- If a key leaks, revoke it first, then create a replacement. A key can change data, not only read it.
The API does not enable cross-origin (CORS) requests, so browser code cannot call it directly.