Platform API

The Platform API handles cross-product concerns including billing, user identity, organization management, SSO/SCIM provisioning, and platform administration.

Overview

The Platform API (apps/platform/) runs on port 3004 and is available at platform-api.statux.io.

Module Structure

apps/platform/src/
├── modules/
│   ├── billing/          # Stripe checkout, portal, webhooks
│   ├── users/            # User profile and subscription
│   ├── organizations/    # Org CRUD, members, product roles
│   ├── identity/         # SSO/SAML and SCIM token management
│   ├── scim/             # SCIM 2.0 user/group provisioning
│   ├── org-audit/        # Cross-product audit logs
│   ├── org-reports/      # Organization reporting
│   └── platform-admin/   # Internal admin tools
├── health/               # Health check endpoints
├── entities/             # TypeORM entities
├── migrations/           # Database migrations
└── main.ts               # Application bootstrap

Endpoints

Auth Cookies

These endpoints are registered on all APIs (including Platform) via AuthCookieController from @app/auth:

Method	Endpoint	Auth	Description
POST	/auth/set-cookie	JWT	Store tokens in httpOnly cookies
GET	/auth/me	Cookie/JWT	Get current user from session
POST	/auth/refresh	Cookie	Refresh tokens using refresh cookie
POST	/auth/logout	Public	Clear httpOnly auth cookies

Health

Method	Endpoint	Auth	Description
GET	/api/v1/health	Public	Health check for ALB
GET	/api/v1/health/live	Public	Liveness probe
GET	/api/v1/health/ready	Public	Readiness probe (checks DB)

Users

Method	Endpoint	Auth	Description
GET	/api/v1/users/me	JWT	Get current user profile (includes isEmployee flag)
PATCH	/api/v1/users/me	JWT	Update user profile
GET	/api/v1/users/me/subscription	JWT	Get user subscription status

GET /users/me returns the user's Cognito profile plus isEmployee from the database. The isEmployee field is used by the internal docs site to gate access.

Billing

Method	Endpoint	Auth	Description
POST	/api/v1/billing/checkout	JWT	Create Stripe checkout session
GET	/api/v1/billing/portal	JWT	Get Stripe billing portal URL
GET	/api/v1/billing/status	JWT	Check if billing is enabled
POST	/api/v1/billing/webhook	Public	Stripe webhook receiver
POST	/api/v1/billing/setup	Platform Admin	Create Stripe products/prices
GET	/api/v1/billing/products	Platform Admin	List Stripe products

Org-scoped Billing

Method	Endpoint	Auth	Description
POST	/api/v1/billing/organizations/:orgId/billing/checkout	Org Owner	Create checkout for org
GET	/api/v1/billing/organizations/:orgId/billing/portal	Org Owner	Get billing portal for org

Organizations

Method	Endpoint	Auth	Description
GET	/api/v1/organizations	JWT	List user's organizations
POST	/api/v1/organizations	JWT	Create organization
GET	/api/v1/organizations/:orgId	Org Member	Get organization details
PATCH	/api/v1/organizations/:orgId	Org Admin/Owner	Update organization
DELETE	/api/v1/organizations/:orgId	Org Owner	Delete organization

Members

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/members	Org Member	List members
POST	/api/v1/organizations/:orgId/members	Org Admin/Owner	Add member
PATCH	/api/v1/organizations/:orgId/members/:memberId	Org Owner	Update member role
PUT	/api/v1/organizations/:orgId/members/:memberId	Org Admin/Owner	Update member (role + product roles)
DELETE	/api/v1/organizations/:orgId/members/:memberId	Org Admin/Owner	Remove member
POST	/api/v1/organizations/:orgId/transfer-ownership	Org Owner	Transfer ownership

Product Roles

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/product-role-options	Org Member	Get valid product role options
GET	/api/v1/organizations/:orgId/members/:memberId/product-roles	Org Member	Get member's product roles
PUT	/api/v1/organizations/:orgId/members/:memberId/product-roles	Org Admin/Owner	Set member's product roles

Subscription

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/subscription	Org Member	Get org subscription

SSO / SAML

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/sso	Org Admin/Owner	Get SSO config status
POST	/api/v1/organizations/:orgId/sso	Org Admin/Owner	Configure SSO/SAML
DELETE	/api/v1/organizations/:orgId/sso	Org Admin/Owner	Remove SSO config
GET	/api/v1/organizations/:orgId/sso/metadata	Public	Get SAML SP metadata

SCIM Tokens

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/scim-tokens	Org Admin/Owner	List SCIM tokens
POST	/api/v1/organizations/:orgId/scim-tokens	Org Admin/Owner	Create SCIM token
DELETE	/api/v1/organizations/:orgId/scim-tokens/:id	Org Admin/Owner	Revoke SCIM token

SCIM 2.0 Provisioning

These endpoints follow the SCIM 2.0 specification and are authenticated via SCIM bearer tokens (not JWT).

Method	Endpoint	Auth	Description
GET	/api/v1/scim/v2/ServiceProviderConfig	SCIM Token	Service provider config
GET	/api/v1/scim/v2/Schemas	SCIM Token	Supported schemas
GET	/api/v1/scim/v2/ResourceTypes	SCIM Token	Supported resource types
GET	/api/v1/scim/v2/Users	SCIM Token	List users
GET	/api/v1/scim/v2/Users/:id	SCIM Token	Get user
POST	/api/v1/scim/v2/Users	SCIM Token	Create user
PUT	/api/v1/scim/v2/Users/:id	SCIM Token	Replace user
PATCH	/api/v1/scim/v2/Users/:id	SCIM Token	Update user
DELETE	/api/v1/scim/v2/Users/:id	SCIM Token	Deactivate user
GET	/api/v1/scim/v2/Groups	SCIM Token	List groups
GET	/api/v1/scim/v2/Groups/:id	SCIM Token	Get group
POST	/api/v1/scim/v2/Groups	SCIM Token	Create group
PUT	/api/v1/scim/v2/Groups/:id	SCIM Token	Replace group
PATCH	/api/v1/scim/v2/Groups/:id	SCIM Token	Update group
DELETE	/api/v1/scim/v2/Groups/:id	SCIM Token	Delete group

Org Audit Logs

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/audit-logs	Org Member	List audit logs (filterable by product, entity type, action, date range)

Org Reports

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/reports	Org Member	List reports
GET	/api/v1/organizations/:orgId/reports/:reportId/download	Org Member	Get signed download URL
POST	/api/v1/organizations/:orgId/reports/generate	Org Member	Generate a new report
GET	/api/v1/organizations/:orgId/status-pages	Org Member	List org status pages
GET	/api/v1/organizations/:orgId/checks	Org Member	List org synthetics checks

Billing Integration

Pricing Model

• Per-product: Pages, Alerts, Synthetics ($65 Team / $150 Business per month)
• Bundle: All products ($150 Team / $400 Business per month)
• Enterprise: Custom pricing

Checkout Flow

POST /api/v1/billing/checkout
{ "product": "bundle", "plan": "team" }
// Returns { url: "https://checkout.stripe.com/..." }

Webhook Events Handled

The Stripe webhook endpoint processes the following events:

• checkout.session.completed - Subscription created
• customer.subscription.updated - Plan changes
• customer.subscription.deleted - Cancellation
• invoice.payment_failed - Payment failures

Database

The Platform API uses the core schema for its own entities and shares it with the cross-product shared entities.

Key Tables

Table	Purpose
core.users	User profiles
core.organizations	Organization records
core.organization_members	Org membership
core.org_product_roles	Per-product role assignments
core.subscriptions	Legacy billing subscriptions
core.org_product_subscriptions	Per-product subscription per org
core.scim_tokens	SCIM provisioning tokens
core.analytics_events	Product usage telemetry
core.user_activities	User activity tracking

Testing

Run tests with:

npm run test:platform