Authentication

How skcal authenticates the app, the CLI, agents, and the scale ingest.

skcal uses Better Auth with phone-number sign-in: you enter your number, we text a 6-digit code, and a new number creates an account. Every request is scoped to the signed-in account, so you only ever see your own data.

Web app

Signing in sets a secure, HttpOnly session cookie. Browser requests to the API carry it automatically, so there’s nothing to configure.

iPhone and Android apps

The mobile apps sign in the same way, then send the session as Authorization: Bearer <token> instead of a cookie.

CLI

skcal login opens your browser to sign in with your phone number, then caches an OAuth token locally, which the CLI replays on each request. See the CLI page for details.

API keys (programmatic access)

Create bearer API keys in the app under profile → API keys. Send them as:

curl https://app.skcal.fit/api/dashboard \
  -H "Authorization: Bearer skcal_your_key_here"

Keys default to full access. You can limit a key to specific resource:action scopes (e.g. weight:read, nutrition:write); a request outside a key’s scopes returns 403. Scopes:

Resource	Scopes
weight	`weight:read`, `weight:write`
measurements	`measurements:read`, `measurements:write`
nutrition	`nutrition:read`, `nutrition:write`
targets (and phases)	`targets:read`, `targets:write`
training	`training:read`, `training:write`
dashboard	`dashboard:read`
agent	`agent:read`, `agent:write`

Agents (MCP)

The MCP server is authorized with OAuth 2.1. Clients discover the endpoints, register dynamically, run the PKCE authorization-code flow against your skcal login, and receive a token scoped to your account. This is the smoothest path for AI clients.

Scale ingest

The single write endpoint POST /api/ingest/weight accepts a shared bearer token so a smart scale can push readings without a browser session:

curl -X POST https://app.skcal.fit/api/ingest/weight \
  -H "Authorization: Bearer $INGEST_TOKEN" \
  -H "content-type: application/json" \
  -d '{"weightKg": 72.6}'