> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/saas-auth-subscriptions-and-access.md). # SaaS auth, subscriptions & access Account authentication, workspace onboarding, SaaS checkout, subscriptions, entitlements, sessions and access-policy APIs. > **Preview contract** — SaaS access and subscription contracts are still under construction and are not fully production-tested until explicitly marked **Live/Verified**. These endpoints implement the server-authoritative access pipeline used by the public Web app and Studio. ## Context contracts The context endpoints are intentionally separate: | Endpoint | Responsibility | | ------------------------------------------------- | ------------------------------------------------------------------------------ | | `GET /api/v1/auth/context` | Session identity, tenant/account, role, permissions, verified-wallet count | | `GET /api/v1/access/context?path=` | Route/resource access decision for one normalized internal path | | `GET /api/v1/saas/me` | Workspace, subscription, entitlements, effective permissions and feature flags | `/saas/me` is not a route authorization token. `/access/context` is not the subscription ledger. `/auth/context` is not an entitlement projection. ## Recommended shell boot ``` signed session ↓ /auth/context ↓ +--------------------------+ | | /saas/me /access/context?path=current | | workspace UI route decision ``` After Auth Context succeeds, SaaS Me and current-route Access Context may be fetched in parallel. The UI can use these projections to render navigation and upgrade/unavailable states, but server operations must repeat authorization. ## Plans ```http GET /api/v1/saas/plans ``` Returns the active server-backed plan catalog plus currently published price versions. Annual pricing reports unavailable until an annual price version actually exists. Plan catalog data is not equivalent to the current workspace's effective subscription or entitlements. ## Account authentication ```http POST /api/v1/auth/signup POST /api/v1/auth/verify-email POST /api/v1/auth/login POST /api/v1/auth/logout GET /api/v1/auth/session GET /api/v1/auth/sessions POST /api/v1/auth/sessions/revoke-others POST /api/v1/auth/password/forgot POST /api/v1/auth/password/reset ``` Password, verification and reset material remain server-side. Verification/reset database records store hashes rather than reusable raw tokens. Password reset revokes active sessions according to security policy. ## Onboarding and workspace entry ```http POST /api/v1/auth/onboarding POST /api/v1/auth/invite/accept POST /api/v1/auth/handoff POST /api/v1/auth/handoff/exchange ``` Onboarding creates/joins workspace context, records the creator goal and selected plan, and activates Free or routes a paid plan to checkout. Handoff codes are short lived and single use; they exchange a Web session for the Studio HTTP-only session without placing a long-lived credential in a URL. ## Access Context ```http GET /api/v1/access/context?path= ``` This endpoint evaluates one normalized internal path/resource against workspace scope, feature state, subscription/entitlement requirements, permissions and workflow policy. It returns an access decision, not general SaaS account metadata. ## SaaS Me ```http GET /api/v1/saas/me ``` This endpoint returns the current workspace/SaaS projection: * workspace identity/state; * effective subscription, when applicable; * entitlements; * effective permissions; * feature flags. Team members may inherit workspace-subscription entitlements without becoming billing owners. Entitlements never grant Admin authority. ### Subscription and entitlement are separate Examples: * Free workspace: `subscription` may be absent/null while Free entitlements are still present. * Paid workspace: active subscription may grant a specific entitlement set. * Feature rollout: entitlement may exist while `featureFlags.someFeature` is false for the environment/workspace. * Permission boundary: a user may have the entitlement but lack permission to perform a privileged action. Do not collapse those states into one `hasAccess` boolean in persistent domain logic. ## Normalized access failures ``` UNAUTHENTICATED SESSION_EXPIRED ACCESS_DENIED WORKSPACE_ACCESS_DENIED SUBSCRIPTION_REQUIRED ENTITLEMENT_REQUIRED FEATURE_DISABLED ``` Suggested product remediation: | Code | Product handling | | ------------------------------------- | ----------------------------------- | | `UNAUTHENTICATED` / `SESSION_EXPIRED` | Sign-in/reauthentication | | `WORKSPACE_ACCESS_DENIED` | Workspace access/selection state | | `ACCESS_DENIED` | Permission/request-access state | | `SUBSCRIPTION_REQUIRED` | Checkout/upgrade state | | `ENTITLEMENT_REQUIRED` | Plan capability/upgrade explanation | | `FEATURE_DISABLED` | Feature unavailable/deferred state | This mapping is UX policy; the API error class remains unchanged. ## Cache invalidation All context responses are private authority/product state and must not be publicly cached. Recommended browser/CDN policy: ```http Cache-Control: private, no-store ``` `/saas/me` internal projections invalidate on: * membership/workspace changes; * checkout reconciliation; * subscription activation/change/cancellation/expiration; * entitlement grant/revoke; * feature-flag change; * plan/catalog transition; * role/permission changes because effective permissions are part of the response. `/access/context` additionally invalidates on route-policy and resource-scope changes. When invalidation certainty is unavailable, refetch rather than serving stale authority. ## SaaS checkout ```http POST /api/v1/saas/checkout GET /api/v1/saas/checkout/:id POST /api/v1/saas/checkout/:id/reconcile ``` Paid checkout captures an immutable price snapshot. The browser success route is read-only; it cannot activate access. Protected reconciliation persists provider-confirmed payment state before subscription activation. Activation is deduplicated by checkout identity so retries cannot create a second subscription. After successful activation, product entitlements are created and any period AI-credit allowance enters the Credit Ledger through the canonical ledger path. `POST /api/v1/subscriptions` direct paid activation is disabled. Paid activation must use checkout reconciliation. Free activation is performed by onboarding. ## Subscription management ```http GET /api/v1/subscriptions/history POST /api/v1/subscriptions/:id/cancel ``` Cancellation is at period end. The API explicitly reports `refundIssued: false`; automatic commercial refunds are not created by cancellation. ## Administration ```http GET /api/v1/admin/members POST /api/v1/admin/members/invite GET /api/v1/admin/roles GET /api/v1/admin/billing GET /api/v1/admin/audit GET /api/v1/admin/ai ``` These endpoints are RBAC-protected. `super_admin` is a platform role and cannot be granted through ordinary workspace invites. ## Full security/economic flow ``` signed session → auth context → access / entitlement checks → verified wallet context where required → quote / policy validation → TransactionIntent → explicit signature → submission → chain confirmation → effect verification → settlement → reconciliation ``` Each state is separate and server-authoritative. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/saas-auth-subscriptions-and-access.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.