Generated SaaS APIs¶

Target Architecture — Final-State Design

This page documents the representative APIs generated into every SaaS Product. The exact surface varies per product, but the spine APIs below — auth, tenants, users, roles, subscriptions, feature flags, notifications, reports, and configuration — are common to all. All REST paths follow the naming conventions: plural, lowercase, hyphenated collection nouns.

Every generated API is produced from ConnectSoft.MicroserviceTemplate (or the gateway/identity/auth templates), exposes an OpenAPI document, validates OpenIddict-issued bearer tokens, and enforces tenant isolation on every request. Public traffic enters through the API Gateway; internal service-to-service calls use gRPC or internal REST not exposed at the edge.

Surface classification¶

Surface	Audience	Transport	Exposure
Public REST	Portals, mobile, external API consumers	HTTPS/JSON	Through API Gateway
Internal REST	Service-to-service (non-latency-critical)	HTTPS/JSON	Cluster-internal only
gRPC	Service-to-service (latency-sensitive, e.g. entitlement/auth checks)	HTTP/2 + protobuf	Cluster-internal only
Webhooks (outbound)	External subscribers	HTTPS/JSON	Egress via Integration Service

Representative endpoints¶

Resource	Method + Path	Surface	Authorization
Auth	`POST /connect/token`	Public	Client credentials / password / refresh grant
Auth	`GET /.well-known/openid-configuration`	Public	Anonymous
Tenants	`GET /tenants`, `POST /tenants`	Public	`tenant.read` / `tenant.manage` (platform admin)
Tenants	`POST /tenants/{tenantId}/provision`	Internal	`tenant.manage`
Users	`GET /users`, `POST /users/invitations`	Public	`user.read` / `user.invite`
Roles	`GET /roles`, `POST /roles/{roleId}/assignments`	Public	`role.read` / `role.assign`
Subscriptions	`GET /subscriptions`, `POST /subscriptions/{id}/activate`	Public	`subscription.read` / `subscription.manage`
Feature flags	`GET /feature-flags`, `PUT /feature-flags/{key}`	Public	`config.read` / `config.manage`
Notifications	`GET /notifications`, `POST /notifications`	Public	`notification.read` / `notification.send`
Reports	`GET /reports`, `POST /reports/{id}/generate`	Public	`report.read` / `report.generate`
Configuration	`GET /config`, `PUT /config/{key}`	Public	`config.read` / `config.manage`
Entitlements	`Entitlements.Check` (gRPC)	gRPC	service identity + tenant scope

Authorization¶

Authentication — bearer tokens issued by the Authorization Server (OpenIddict). The gateway validates signature, expiry, audience, and issuer before routing.
Authorization — scope/permission claims drive endpoint authorization (RBAC), with attribute-based checks (ABAC) for tenant- and resource-level constraints. See Security.
Tenant scope — the tenantId claim must match the path/route tenant; mismatches are rejected with 403. Platform-admin scopes permit cross-tenant operations on the Tenants resource only.

Versioning¶

APIs are versioned by URL prefix (/v1/...) and by an api-version header for fine-grained negotiation.
Backward-compatible changes (new optional fields, new endpoints) are additive within a version.
Breaking changes introduce /v2/... and run side by side with /v1/... during a deprecation window published in the product's documentation site.
Event contracts follow the separate event versioning rules in the event envelope.

Examples¶

Register a tenant¶

POST /v1/tenants HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Contoso Ltd",
  "slug": "contoso",
  "editionCode": "professional",
  "ownerEmail": "admin@contoso.com"
}

{
  "tenantId": "contoso",
  "name": "Contoso Ltd",
  "slug": "contoso",
  "status": "Provisioning",
  "editionCode": "professional",
  "createdAt": "2026-06-11T09:00:00Z"
}

Invite a user¶

POST /v1/users/invitations HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "jane@contoso.com",
  "roleCodes": ["member"],
  "displayName": "Jane Doe"
}

{
  "invitationId": "inv-8a21",
  "email": "jane@contoso.com",
  "status": "Pending",
  "expiresAt": "2026-06-18T09:00:00Z"
}

Activate a subscription¶

POST /v1/subscriptions/sub-4f7c/activate HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "editionCode": "enterprise",
  "billingCycle": "Annual"
}

{
  "subscriptionId": "sub-4f7c",
  "tenantId": "contoso",
  "editionCode": "enterprise",
  "status": "Active",
  "currentPeriodEnd": "2027-06-11T00:00:00Z"
}

Toggle a feature flag¶

PUT /v1/feature-flags/new-dashboard HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "enabled": true,
  "rolloutPercentage": 25
}

{
  "key": "new-dashboard",
  "enabled": true,
  "rolloutPercentage": 25,
  "updatedAt": "2026-06-11T09:05:00Z"
}

Generate a report¶

POST /v1/reports/rpt-usage/generate HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "format": "pdf",
  "parameters": { "from": "2026-05-01", "to": "2026-05-31" }
}

{
  "reportRunId": "run-2c9d",
  "reportDefinitionId": "rpt-usage",
  "status": "Queued",
  "requestedAt": "2026-06-11T09:06:00Z"
}

How the APIs contribute to the pillars¶

Traceability — every request carries/propagates traceId; responses to async operations return a run id correlatable to the resulting events.
Reusability — generated from the same template, all APIs share error contracts, pagination, and auth conventions.
Autonomy — the API Gateway Generator and Microservice Generator agents produce and version these surfaces from blueprints.
Governance — scope-based authorization and tenant guards are enforced uniformly at the edge and in each service.
Observability — gateway and service-level metrics (latency, error rate, throughput) are emitted per route and tenant.
Multi-tenant scale — tenantId scoping on every endpoint enables per-tenant rate limiting and isolation.