Authentication

Saturday has three authentication methods, one per principal type:

Method	Use case	How it works
Partner API Key	Server-to-server partner integration	`sk_*` Bearer token in the `Authorization` header
Coach API Key	A coach’s own scripts against their roster	`cp_*` Bearer token in the `Authorization` header
OAuth2	Athlete- or coach-delegated access, including the Claude connector	Authorization code flow with PKCE

Most partner integrations start with API keys. Add OAuth2 when you need athletes or coaches to connect their existing Saturday accounts. Coaches automating against their roster use a coach API key, covered in the Coach API.

API keys

All server-to-server requests pass the key in the Authorization header as a Bearer token.

Key types

The prefix encodes both the principal and the environment, so a misrouted key fails closed instead of touching the wrong data.

Prefix	Environment	Purpose
`sk_test_`	Sandbox	Partner key for development and testing
`sk_live_`	Production	Partner key against real athlete data
`cp_test_`	Sandbox	Coach key for a coach’s roster surface (`/v1/coach/*`)
`cp_live_`	Production	Coach key in production. Requires the Business tier or higher

Coach keys (cp_*) are minted in the coach portal under API Keys, not via api@saturday.fit. They authenticate the coach to the Coach API and are confined to that coach’s roster and configuration. A coach whose subscription lapses below Pro Coach loses cp_ key access on the next request. Coach keys use a separate scope vocabulary, chosen at mint time in the portal: roster:read, roster:write, reports:read, org:read, org:write, org:admin, webhooks:manage, billing:read. That is a different model from the partner-key scopes below, and the two do not mix. The portal offers each coach only the scopes their role and plan can mint.

curl -H "Authorization: Bearer $SATURDAY_API_KEY" \
  https://api.saturday.fit/v1/activity-types

Never expose live keys in client-side code. API keys belong in server-to-server requests only. If you suspect a key has been compromised, revoke it immediately.

Getting your keys

Self-serve accounts are issued a key at checkout. It is revealed once on the success page and emailed. If it never arrived, POST /v1/signup/resend with your checkout session id rotates and re-sends it. Platform partners are issued keys as part of the agreement: contact api@saturday.fit with your platform name and use case. See Getting Access for which lane applies to you.

Using your key

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['SATURDAY_API_KEY']}"}
response = requests.get("https://api.saturday.fit/v1/athletes", headers=headers)

const response = await fetch("https://api.saturday.fit/v1/athletes", {
  headers: { Authorization: `Bearer ${process.env.SATURDAY_API_KEY}` },
});

Key management

Creating additional keys. One key per service or deployment stage keeps a compromise contained and makes rotation a non-event.

curl -X POST https://api.saturday.fit/v1/partner/api-keys \
  -H "Authorization: Bearer $SATURDAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production-nutrition-service", "environment": "live", "scopes": ["*"] }'

scopes accepts ["*"] for unrestricted, ["read"] for GET/HEAD/OPTIONS, and ["write"] for POST/PUT/PATCH/DELETE. A read-write key needs both listed: write does not imply read. A request outside a key’s scopes gets a 403 with code insufficient_scope. environment is optional and defaults to the environment of the host you call: live on api.saturday.fit, test on the sandbox host. Naming the other environment, or any other value, is a 400 with code invalid_value, because a key record only ever authenticates on the host that issued it.

Save the key immediately. The full value is returned once at creation. The id in that response is what the rotate and revoke endpoints take, so store it with the key.

Rotating keys. Rotation mints a replacement and revokes the old key in the same call, with no grace period. The old key stops working immediately.

curl -X POST https://api.saturday.fit/v1/partner/api-keys/{key_id}/rotate \
  -H "Authorization: Bearer $SATURDAY_API_KEY"

For a cutover with no downtime, do not rotate. Create a second key, deploy it everywhere, confirm traffic has moved, then revoke the first. Revoking keys. Revocation takes effect immediately.

curl -X DELETE https://api.saturday.fit/v1/partner/api-keys/{key_id} \
  -H "Authorization: Bearer $SATURDAY_API_KEY"

Environments

Environment	Base URL	Data
Production	`https://api.saturday.fit`	Real athlete data
Sandbox	Issued with your `sk_test_` key	Synthetic test data

The key prefix and the base URL travel together. Each environment keeps separate key records, so a key issued by the sandbox does not authenticate against api.saturday.fit, and the reverse.

Sandbox behavior

Athlete data is isolated. Sandbox athletes are not real people
Nutrition calculations run the same engine as production, on sandbox profiles
POST /v1/test/athletes/{athlete_id}/simulate-subscription flips an athlete between tiers and fires the matching webhook. It exists only in sandbox
Teaser subscribe links carry test=1 so the whole checkout loop resolves against sandbox
Rate limits are enforced by the same code path as production, from your account’s configured limits. Sandbox is not exempt
No billing impact

Security practices

Store keys in environment variables, not in source code
Use separate keys for different services and deployment stages
Rotate on a schedule you can keep, and immediately on any suspected exposure
Watch /v1/partner/usage for patterns you cannot account for
Revoke immediately if a key appears in logs, repos, or client code

Error responses

Authentication and authorization failures share the standard error envelope:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "documentation_url": "https://docs.saturday.fit/errors#invalid_api_key",
    "request_id": "req_abc123def456"
  }
}

Code	Type	Status	Meaning
`missing_authorization`	`authentication_error`	401	No `Authorization` header
`invalid_api_key`	`authentication_error`	401	Key doesn’t exist, or the header isn’t `Bearer <token>`
`api_key_revoked`	`authentication_error`	403	Key revoked, or the account is suspended. For a self-serve account this usually means the subscription lapsed, and renewing reactivates the same key
`insufficient_scope`	`authorization_error`	403	The key’s scopes don’t permit this method
`coach_tier_required`	`authorization_error`	403	A `cp_` key whose coach is below Pro Coach
`internal_error`	`api_error`	503	Key verification is temporarily unavailable. Retry rather than rotating a working key

A key used against the wrong environment fails closed as invalid_api_key, and the message names the environment the key was issued for. Each environment keeps separate key records, and a record whose environment is not the host’s is refused even if it is present.

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Authentication

Authentication

API keys

Key types

Getting your keys

Using your key

Key management

Environments

Sandbox behavior

Security practices

Error responses

​Authentication

​API keys

​Key types

​Getting your keys

​Using your key

​Key management

​Environments

​Sandbox behavior

​Security practices

​Error responses

Authentication

API keys

Key types

Getting your keys

Using your key

Key management

Environments

Sandbox behavior

Security practices

Error responses