Partner API and studio API keys

A studio API key is a secret that identifies one studio to a machine caller. Three surfaces accept it:

Surface	Base path	Consumer
Partner lane	`/v1/partner`	SmartSend, for the trainee panel and campaign audiences
Automation lane	`/v1/automation`	Make and other automation tools. See Automation API
MCP endpoint	`/mcp`	AI clients. See MCP server

All three use the same key table and the same verification.

Studio API keys

Format

pf_live_ + 40 hex characters

generatePartnerSecret in apps/core-api/src/modules/partner/api-keys.service.ts joins PARTNER_KEY_PREFIX (pf_live_) with 20 random bytes as hex.

Storage

The plaintext is never stored. StudioApiKey keeps:

Column	Value
`keyHash`	`hashPartnerKey(secret)`, the SHA-256 hex digest. Unique.
`prefix`	The first 15 characters of the secret, so the settings page can show which key is which.
`name`	The label the coach typed.
`scopes`	Defaults to `["panel"]`.
`lastUsedAt`	A coarse usage stamp.
`revokedAt`	Set on revoke.

scopes is stored but not checked. requirePartnerKey reads only the hash, revokedAt and the studio’s deletedAt. Every valid key can call every endpoint on all three surfaces. If you add scoping, this middleware is where it goes.

Management

Mounted on the web lane at /v1/web/studios/current/api-keys, restricted to OWNER and HEAD_COACH.

Route	Purpose
`GET /`	List the studio’s keys. Returns `{ keys }`. Never includes a secret.
`POST /`	Create a key. Body: `{ name }`, 1 to 100 characters. Returns `{ key, secret }`.
`POST /:id/revoke`	Revoke. `NOT_FOUND` “api key not found” when the id is not in this studio. Returns `{ ok: true }`.

The create response is the only place the plaintext secret ever appears. A lost key cannot be recovered. Revoke it and issue a new one.

Verification

requirePartnerKey(store) in apps/core-api/src/modules/partner/partner-auth.ts:

Authorization: Bearer YOUR_API_KEY

The header must be a bearer token that starts with pf_live_. Otherwise UNAUTHORIZED, “missing partner api key”.
The secret is hashed and looked up by keyHash.
No row, a revoked row, or a key whose studio is archived fails with UNAUTHORIZED, “invalid partner api key”. An archived studio’s keys stop working even before they are revoked.
lastUsedAt is stamped at most once per 5 minutes per key (LAST_USED_THROTTLE_MS), fire and forget. A usage stamp must never fail a request.
req.partner is set to { studioId, apiKeyId }.

Every request resolves to exactly one studio. Every query in these lanes must be scoped to partnerOf(req).studioId.

Rate limits

The partner and automation lanes sit under /v1, so they share the global limiter: RATE_LIMIT_MAX requests per RATE_LIMIT_WINDOW_MS, defaults 120 per 60 seconds. /mcp is mounted with the same limiter.

Keys the system creates

Not every key is made by a coach:

The WhatsApp AI assistant mints one per studio and stores its plaintext in Studio.settings.agent.apiKey. The row is visible in the integrations list, and revoking it disconnects the assistant.

Deleting a key’s hooks

AutomationHook.apiKeyId cascades from StudioApiKey. Hooks are tied to the key that registered them.

The partner lane

apps/core-api/src/modules/partner. The router applies requirePartnerKey to everything. Responses on this lane are a wire contract with SmartSend. They are returned as plain JSON with no ok and data envelope, unlike the web lane. The automation lane has its own envelope and its own error mapper precisely so this contract never has to shift.

Endpoints

Route	Purpose
`GET /v1/partner/ping`	Key check. Returns `{ ok: true, studio: { id, name, slug } }`.
`GET /v1/partner/reports`	The static report catalog.
`GET /v1/partner/reports/:key`	One audience report.
`GET /v1/partner/trainees/by-phone/:phone`	Find a trainee by phone.
`GET /v1/partner/trainees/:id/overview`	The trainee panel’s main payload.
`GET /v1/partner/trainees/:id/workouts`	Paged workout history.
`GET /v1/partner/trainees/:id/nutrition-days`	Nutrition per day in a date range.
`GET /v1/partner/trainees/:id/forms`	Submitted forms.
`GET /v1/partner/trainees/:id/forms/:responseId`	One form response.
`GET /v1/partner/trainees/:id/weights`	Weigh-ins.
`GET /v1/partner/trainees/:id/programs`	The trainee’s training or nutrition program.
`GET /v1/partner/trainees/:id/tasks`	Open tasks about the trainee.
`POST /v1/partner/trainees/:id/freeze`	Freeze the subscription.
`POST /v1/partner/trainees/:id/reactivate`	Reactivate it.
`GET /v1/partner/trainees/:id/activity`	The trainee card’s activity feed.
`POST /v1/partner/trainees/:id/activity/notes`	Add a note.
`DELETE /v1/partner/trainees/:id/activity/notes/:activityId`	Delete a note.

A trainee id that is not in the key’s studio is NOT_FOUND.

Parameters

From partner.schema.ts:

Endpoint	Parameters
`by-phone/:phone`	`phone`, at least 6 characters. Matched through phone variants, so local and international forms both find the trainee.
`workouts`	Query `page` (default 1), `pageSize` (default 20, max 100).
`nutrition-days`	Query `from` and `to`, both required, `YYYY-MM-DD`.
`programs`	Query `type`, required: `TRAINING` or `NUTRITION`.
`activity`	Query `viewer`, optional: the SmartSend user id of the person looking.
`activity/notes` (POST)	Body `text` (up to 10000 characters) and `author: { id, name? }`.
`activity/notes/:activityId` (DELETE)	Query `author`, the SmartSend user id.

Response shapes

by-phone:

{ "found": true, "clientId": "CLIENT_ID", "name": "TRAINEE_NAME" }

or { "found": false }. overview returns one object with these top-level keys: client, links, subscriptions, weeksInProcess, today, targets, training, counters, weeklyRating, weight, photos, latestCheckin. links holds deep links into the coach web app, built from APP_WEB_URL. workouts: { items, total, page, pageSize }. nutrition-days: { days }, one entry per day, computed from the plan and the trainee’s day snapshot with the same arithmetic the app uses. forms: { items }. forms/:responseId: { responseId, formName, formType, submittedAt, answers }. weights: { items }. programs: { program }, or { program: null } when the trainee has none of that type. The program has id, name, status, startsOn, endsOn, editUrl, pdfUrl and days. A file plan returns days: []. tasks: { items }. freeze and reactivate: { subscription }, the subscription now in that state or null. activity: { activity, viewerActorId }.

Freeze and reactivate

Both call the same client subscription service the coach web uses, so the same rules apply. Each writes an AuditLog row with actorId set to the API key id and action partner.freeze or partner.reactivate.

Notes and who the author is

A SmartSend user writes a note about a trainee from inside SmartSend. resolvePartnerActor decides who that is in Perform:

If the studio’s SmartSend settings map that SmartSend user id to a Perform coach (Studio.settings.smartsend.userMap), the note belongs to that coach. They can see and delete it in Perform too.
Otherwise the actor id is smartsend:<userId> and the name is “SmartSend” plus the author’s name.

viewerActorId in the activity response tells the panel which actor the viewer would act as, so it knows which notes are the viewer’s own and may be deleted. Creating and deleting a note are audited as partner.activity_note.create and partner.activity_note.delete.

Audience reports

Reports turn a studio question into a list of trainees SmartSend can message. A report’s clients become a SmartSend mailing list, and every context key becomes a per-recipient field usable as a template variable.

`GET /v1/partner/reports`

Returns { reports }, the static REPORTS_CATALOG from reports.schema.ts. SmartSend renders its picker straight from this, so adding a report here ships to the SmartSend UI with no deploy on their side.

{
  "reports": [
    {
      "key": "workout-goal",
      "description": "REPORT_DESCRIPTION",
      "params": [{ "name": "segment", "type": "string", "required": true, "enum": ["reached", "not_reached"] }],
      "context": ["name", "coachName", "workoutsThisWeek", "weeklyGoal"]
    }
  ]
}

Descriptions are in Hebrew.

`GET /v1/partner/reports/:key`

`key`	Parameters	Context fields
`workout-goal`	`segment`, required: `reached` or `not_reached`	`name`, `coachName`, `workoutsThisWeek`, `weeklyGoal`
`inactive`	`days`, optional, 1 to 90, default 7	`name`, `coachName`, `daysInactive`, `lastCheckInDate`
`plan-expiry`	`status`, required: `expiring` or `expired`. `days`, optional, 1 to 90, default 21	`name`, `coachName`, `planName`, `endsOnDate`, `daysRemaining`
`birthdays`	none	`name`, `coachName`, `birthDate`, `age`
`open-forms`	none	`name`, `coachName`, `pendingFormNames`, `pendingFormCount`

Response:

{
  "report": "workout-goal",
  "clients": [
    {
      "id": "CLIENT_ID",
      "firstName": "FIRST_NAME",
      "lastName": "LAST_NAME",
      "phoneNumber": "972500000000",
      "email": "trainee@example.com",
      "gender": "female",
      "context": { "name": "FULL_NAME", "coachName": "COACH_NAME", "workoutsThisWeek": 2, "weeklyGoal": 3 }
    }
  ],
  "total": 41,
  "skippedNoPhone": 3
}

Rules, from backend/docs/PARTNER_REPORTS.md and the reports service:

Only trainees with status ACTIVE who are not deleted are included. Frozen and archived trainees are never in a messaging audience.
phoneNumber is in MSISDN form. Trainees with no phone are skipped and counted in skippedNoPhone.
context values are flat scalars only.
The reports service is given the studio’s time zone (studioTimezone) for its date arithmetic.

backend/docs/PARTNER_REPORTS.md states the inactive report accepts days from 3 to 90. The Zod schema inactiveQuery accepts 1 to 90. The schema is what runs.

Adding a partner endpoint

Add the Zod schema to partner.schema.ts.
Add the repository query, always filtered by studioId.
Add the service method. Call requireClient(studioId, clientId) first for anything about a trainee.
Add the controller method. Return the shape directly with res.json. Do not use the ok helper on this lane.
Register the route in partner.routes.ts.
For a write, add an AuditLog row with the API key id as the actor.

Treat every shape as frozen once SmartSend consumes it. Add fields. Do not rename or remove them.

​Studio API keys

​Format

​Storage

​Management

​Verification

​Rate limits

​Keys the system creates

​Deleting a key’s hooks

​The partner lane

​Endpoints

​Parameters

​Response shapes

​Freeze and reactivate

​Notes and who the author is

​Audience reports

​GET /v1/partner/reports

​GET /v1/partner/reports/:key

​Adding a partner endpoint

Studio API keys

Format

Storage

Management

Verification

Rate limits

Keys the system creates

Deleting a key’s hooks

The partner lane

Endpoints

Parameters

Response shapes

Freeze and reactivate

Notes and who the author is

Audience reports

`GET /v1/partner/reports`

`GET /v1/partner/reports/:key`

Adding a partner endpoint