Auth endpoints

Coach and staff identity is handled by better-auth. It runs inside the core API process and is reached under /api/auth/*. It owns users, sessions, organizations, invitations, passkeys and two-factor. The trainee app does not use it at all. Trainees sign in with their own token, described on Trainee sign-in. This page covers three things: how /api is mounted, the better-auth endpoints the web app relies on with the rules this project adds to them, and the small auth module in the core API that verifies sessions.

How `/api` is mounted

src/app.ts mounts honoGateway (src/middleware/hono-gateway.ts) at /api. The gateway rebuilds a web Request from the Express request and hands it to the Hono app exported by @repo/api (backend/packages/api/src/index.ts), then copies the response back. The Hono app has base path /api and these routes:

Path	Handler
`GET` and `POST /api/auth/**`	`auth.handler` from `@repo/auth`, the better-auth instance
`POST /api/webhooks/payments`	`webhookHandler` from `@repo/payments`
`GET /api/health`	Plain text `OK`
`/api/rpc/*`	The oRPC `RPCHandler` over the router in `packages/api/src/orpc/router.ts` (`admin`, `organizations`, `users`, `payments`, `notifications`)
Everything else under `/api`	The oRPC `OpenAPIHandler` over the same router. Its reference plugin serves interactive docs at `/api/docs`, with the better-auth OpenAPI schema merged in under `/auth`

Gateway details that affect clients:

Bodies. The gateway forwards req.rawBody. Only the JSON parser and the application/octet-stream parser capture raw bytes in app.ts, so a request with another content type reaches better-auth without a body. Send JSON.
Cookies. Set-Cookie headers are copied one by one with getSetCookie(). An impersonation response sets three cookies, and joining them into one header made browsers drop all of them.
CORS. The Hono app allows the origins from getTrustedOrigins(NEXT_PUBLIC_SAAS_URL) with credentials, methods GET, POST and OPTIONS, and headers Content-Type and Authorization.
Limits. /api is not behind either Express rate limiter. better-auth’s own protections apply.
Envelope. Responses are better-auth’s and oRPC’s own shapes, never the { ok, data } envelope.

The web app calls these endpoints through the better-auth client (authClient). Requests and responses follow the better-auth version installed in packages/auth. For exact request and response schemas use the generated reference at /api/docs on a running API, not this page.

Sessions

Configured in backend/packages/auth/src/auth.ts and config.ts:

Sessions are stored in the database through the Prisma adapter and carried in a cookie. expiresIn is 30 days (sessionCookieMaxAge = 60 * 60 * 24 * 30). freshAge is 0, so no action requires a recently created session.
baseURL and trusted origins come from NEXT_PUBLIC_SAAS_URL.
Users have three additional fields: onboardingComplete, locale and lastActiveOrganizationId.
When a session is created, a database hook sets activeOrganizationId to the user’s lastActiveOrganizationId, or to the organization returned by claimStaffSeats. That function links staff who were added in the team directory by email to their account and membership, so a first-time staff member lands inside their studio.
Account linking is enabled for the trusted providers google and github.

The session cookie stays between the browser and the web app. The web app’s server reads the session, then calls /v1/web/* with a service signature and the user’s ids as headers. See Authentication.

Plugins

Plugin	What it adds here
`username()`	Username sign-in fields
`admin()`	Platform admin: list users, set role, impersonate
`passkey()`	WebAuthn passkeys
`magicLink`	Email magic links, sent with the `magicLink` mail template
`organization`	Organizations, members and invitations. An organization is a studio
`phoneNumber`	Phone sign-in with a WhatsApp code
`emailOTP`	Email sign-in with a code. Sign-up through it is disabled
`openAPI()`	The schema merged into `/api/docs`
`invitationOnlyPlugin()`	Blocks email sign-up without a pending invitation when `config.enableSignup` is `false`. It is `true` today, so the check is inactive
`twoFactorWithOtpLanes()`	better-auth’s two-factor plugin, widened so the second-factor challenge also fires after `/phone-number/verify` and `/sign-in/email-otp`. Without it a user with 2FA could skip the challenge by signing in with a one-time code

Email and password sign-in is enabled with a minimum password length of 8, automatic sign-in after sign-up, and no required email verification. Social providers are Google and GitHub, configured from GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET.

Endpoints the web app relies on

The list below is taken from the authClient calls in frontend/apps/saas. Paths follow better-auth’s mapping from client method to route. The ones marked “hooked” are referenced by path in this repo’s own hooks and are confirmed from code. The rest are better-auth defaults: confirm them against /api/docs before depending on a detail.

Client call	Endpoint	Project rules
`signUp.email`	`POST /api/auth/sign-up/email`	Hooked. A `phoneNumber` in the body must pass `isValidLoginPhoneNumber` and is rewritten to international digits (`toMsisdn`). Otherwise 400 `INVALID_PHONE_NUMBER`
`signIn.email`	`POST /api/auth/sign-in/email`	Password sign-in
`signIn.social`	`POST /api/auth/sign-in/social`	Google or GitHub. A full-page redirect
`signIn.magicLink`	`POST /api/auth/sign-in/magic-link`	Sends the link by email
`phoneNumber.sendOtp`	`POST /api/auth/phone-number/send-otp`	Hooked. See phone sign-in below
`phoneNumber.verify`	`POST /api/auth/phone-number/verify`	Hooked. Also triggers the 2FA challenge when enabled
`emailOtp.sendVerificationOtp`	`POST /api/auth/email-otp/send-verification-otp`	Hooked. See email code sign-in below
`signIn.emailOtp`	`POST /api/auth/sign-in/email-otp`	Hooked through the 2FA wrapper
`signIn.passkey`	The passkey plugin’s authentication endpoints
`twoFactor.verifyTotp`	`POST /api/auth/two-factor/verify-totp`	Completes a 2FA challenge
`signOut`	`POST /api/auth/sign-out`

Session and account

Client call	Endpoint	Project rules
`getSession`	`GET /api/auth/get-session`	Hooked. Also called by the core API’s session verifier
`listSessions`, `revokeSession`	`/api/auth/list-sessions`, `/api/auth/revoke-session`
`updateUser`	`POST /api/auth/update-user`	Hooked. When the body sets `onboardingComplete: true` and the update succeeds, `markOnboardingFinished` stamps the user’s studios so plan limits start applying
`changeEmail`	`POST /api/auth/change-email`	Sends a confirmation with the `emailVerification` template
`changePassword`, `requestPasswordReset`, `resetPassword`	`/api/auth/change-password`, `/api/auth/request-password-reset`, `/api/auth/reset-password`	The reset mail uses the `forgotPassword` template
`sendVerificationEmail`	`POST /api/auth/send-verification-email`	Not sent automatically on sign-up
`listAccounts`, `linkSocial`	`/api/auth/list-accounts`, `/api/auth/link-social`
`deleteUser`	`POST /api/auth/delete-user`	Enabled. A database hook runs `beforeUserDelete`: personal subscriptions stop and the user’s `Coach` rows are deactivated in every studio. The rows stay for history
`twoFactor.enable`, `twoFactor.disable`	`/api/auth/two-factor/enable`, `/api/auth/two-factor/disable`
`passkey.addPasskey`, `passkey.listUserPasskeys`, `passkey.deletePasskey`	The passkey plugin’s endpoints

Organizations

Client call	Endpoint	Project rules
`organization.create`, `update`, `list`, `setActive`, `getFullOrganization`	`/api/auth/organization/create`, `update`, `list`, `set-active`, `get-full-organization`	Slugs in `config.organizations.forbiddenOrganizationSlugs` are reserved by the web app’s routes, for example `admin`, `settings` and `sign`
`organization.delete`	`POST /api/auth/organization/delete`	`beforeDeleteOrganization` runs after better-auth’s own permission checks. Billing stops and the studio is archived in the same process: `Studio.deletedAt` is set, the organization id is released, the slug is parked, clients are archived, and push tokens, API keys, webhooks and automations stop
`organization.inviteMember`	`POST /api/auth/organization/invite-member`	The invitation mail links to `/login` for an existing user and `/signup` for a new one, with `invitationId` and `email` in the query
`organization.acceptInvitation`	`POST /api/auth/organization/accept-invitation`	Hooked. Seats on the organization’s subscription are updated and `provisionCoach` creates the member’s coach row through Internal endpoints
`organization.rejectInvitation`, `cancelInvitation`	`/api/auth/organization/reject-invitation`, `cancel-invitation`
`organization.updateMemberRole`	`POST /api/auth/organization/update-member-role`	Hooked. The coach row’s role follows: `admin` or `owner` becomes `HEAD_COACH`, anything else `SUB_COACH`
`organization.removeMember`	`POST /api/auth/organization/remove-member`	Hooked. Subscription seats are updated

Platform admin

Client call	Endpoint
`admin.listUsers`	`/api/auth/admin/list-users`
`admin.setRole`	`/api/auth/admin/set-role`
`admin.impersonateUser`, `admin.stopImpersonating`	`/api/auth/admin/impersonate-user`, `/api/auth/admin/stop-impersonating`

Coaches can sign in with a WhatsApp code. The rules are in the hooks.before middleware and lib/phone-otp.ts. The five phone paths (/sign-in/phone-number, /phone-number/send-otp, /phone-number/verify, /phone-number/request-password-reset, /phone-number/reset-password) share one guard:

phoneNumber must be present and pass isValidLoginPhoneNumber. Otherwise the request fails with 400 and code INVALID_PHONE_NUMBER.
The number is normalized to international digits before better-auth sees it, so every lane stores and compares one form.
On /phone-number/send-otp without a session, the number must resolve to a user (resolveUserIdForLoginPhone). Otherwise 400 with code PHONE_NUMBER_NOT_EXIST. With a session the check is skipped, because that is the “change my number” flow.

resolveUserIdForLoginPhone does more than look up the user table. Coaches historically had their phone only on the studio’s Coach row. The function matches the coach row by phone, links it to an account by externalUserId or by the directory email, and provisions an account from the directory entry for a listed staff member who has never signed in. Code settings, shared with the email lane:

Setting	Value
Code length	6 digits
Lifetime	300 seconds
Allowed attempts	3

The code is sent with the WhatsApp template registercode in Hebrew (sendLoginOtpOverWhatsapp).

curl -X POST 'https://perform-api.otherwise.co.il/api/auth/phone-number/send-otp' \
  -H 'content-type: application/json' \
  -d '{"phoneNumber":"0500000000"}'

emailOTP runs with disableSignUp: true, so better-auth silently skips the send for an unknown email. That left staff who were only listed in the team directory with a code that never arrived. The before hook fixes it: on /email-otp/send-verification-otp with type sign-in, provisionStaffAccountForEmail creates an account from the directory entry when the email belongs to a listed staff member. The account has no password and an unverified email, and the seat is claimed when the session is created.

Errors

better-auth errors are JSON with a code and a message, with the HTTP status of the error. The codes this project adds:

Code	Status	Where
`INVALID_PHONE_NUMBER`	400	Sign-up with a bad phone, and all phone paths
`PHONE_NUMBER_NOT_EXIST`	400	`/phone-number/send-otp` for an unregistered number
`INVALID_INVITATION`	400	Email sign-up without an invitation, only when sign-up is closed

Every better-auth API error is logged through onAPIError.

The `auth` module in the core API

src/modules/auth/ has no routes. It holds session-verifier.ts, which turns a better-auth session token into the principal used by the bearer lane.

Factory	When used	How it verifies
`createInProcessSessionVerifier(auth)`	`SESSION_VERIFY_INPROCESS` is `true` or `1`	Calls `auth.api.getSession` directly with an `Authorization: Bearer` header
`createSessionVerifier(betterAuthUrl)`	Otherwise	Fetches `BETTER_AUTH_URL/api/auth/get-session` with the same header

Both map the result with principalFromSession:

userId is user.id.
studioId is the session’s activeOrganizationId.
role comes from the member role: owner to OWNER, admin to HEAD_COACH, member or anything else to SUB_COACH.
A session with no user or no active organization is rejected.

authenticate in src/middleware/auth.ts uses the verifier and answers 401 missing bearer token or invalid session. It guards only the three bearer mounts listed on the API overview.

packages/auth/src/auth.ts does not register better-auth’s bearer plugin, and the session lookup above depends on better-auth accepting a session token in the Authorization header. Whether get-session resolves such a token in this setup is not confirmed from code. Test it before building a client on the bearer lane.

Environment

Variable	Used for
`BETTER_AUTH_SECRET`	better-auth’s signing secret. Also signs trainee tokens and onboarding tokens, so rotating it signs every trainee out
`BETTER_AUTH_URL`	Where the HTTP session verifier calls `get-session`
`SESSION_VERIFY_INPROCESS`	Use the in-process verifier
`NEXT_PUBLIC_SAAS_URL`	better-auth `baseURL`, trusted origins, invitation links
`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`	Social sign-in
`CORE_API_URL`, `CORE_API_SERVICE_ID`, `SERVICE_AUTH_SECRET`	`provisionCoach` calling `/v1/internal/coaches`

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

How `/api` is mounted

Sessions

Plugins

Endpoints the web app relies on

Session and account

Organizations

Platform admin

Errors

The `auth` module in the core API

Environment

​How /api is mounted

​Sessions

​Plugins

​Endpoints the web app relies on

​Sign-in and sign-up

​Session and account

​Organizations

​Platform admin

​Phone sign-in

​Email code sign-in

​Errors

​The auth module in the core API

​Environment

How `/api` is mounted

Sessions

Plugins

Endpoints the web app relies on

Sign-in and sign-up

Session and account

Organizations

Platform admin

Phone sign-in

Email code sign-in

Errors

The `auth` module in the core API

Environment