Skip to main content

​
Authentication

PlanSync supports two ways to call protected APIs:
  1. Project API keys (x-api-key) — preferred for integrations and the docs playground
  2. Better Auth session cookies — used by the signed-in web app

​
Project API keys

Create a key in Project Settings → API keys. Keys look like psk_… and are sent as a header:
Notes:
  • API keys only work on project-scoped routes: /api/v1/projects/{projectId}/…
  • The {projectId} in the path must match the project the key belongs to
  • Scopes are enforced (for example issues:read to list issues, issues:write to create)
  • Do not paste an API key into the session cookie field in the playground

​
Session cookies

For browser/session flows:
  • Authenticate through /api/auth/*
  • Send the Better Auth session cookie with the request

​
Email verification behavior

Most session-protected routes require verified email status. Possible responses:
  • 401 Unauthorized when no valid session or API key exists
  • 403 Email verification required when a user is signed in but not verified
  • 403 API key missing scope: … when the key lacks the required scope
Invite acceptance flows are an exception and can run before verification finalization.

​
Authorization model

After authentication, route-level checks enforce:
  • Workspace membership
  • Project membership
  • Manager/admin/super-admin requirements for management actions
  • Plan requirements for premium features

​
Public token routes

Some APIs do not require member sessions but do require opaque tokens:
  • Proposal portal endpoints (/api/v1/public/proposals/:token/*)
  • Occupant endpoints (/api/v1/occupant/:token/*)
Treat these tokens as secrets. Example token route:

​
Internal automation routes

Certain routes are intended for your own secure infrastructure and use a secret header/key pattern (for scheduled jobs). Do not expose these routes directly to customer systems.