> 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/session-roles-and-administrative-policy-api.md). # Session, Roles & Administrative Policy API Preview authentication context, route access, SaaS state, roles, wallet and administrative policy contracts for the SONIC platform. **Status:** `Preview` These administrative and context contracts remain under construction and must not be represented as `Live` or `Verified` until the owning validation requirements are explicitly completed. ## Context endpoints | 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 the requested internal path | | `GET /api/v1/saas/me` | Workspace, subscription, entitlements, permissions and feature flags | ### Authenticated context ```http GET /api/v1/auth/context ``` Returns sanitized session authority: tenant, user/account identity, role, safe permission identifiers and verified-wallet count. Wallet transaction authorization remains separate and client state is not authoritative. ### Route/resource access context ```http GET /api/v1/access/context?path= ``` Returns the access decision for one normalized internal path/resource. It evaluates workspace scope, route policy, feature state, entitlement and permission requirements. ### SaaS workspace context ```http GET /api/v1/saas/me ``` Returns workspace, subscription, entitlement, effective-permission and feature-flag state. It is not a route-specific authorization response. ## Context dependency ``` SIGNED SESSION ↓ AUTH CONTEXT ↓ +--------------------+ | | ACCESS CONTEXT SAAS ME | | route policy subscription workspace scope entitlements feature access feature flags ``` ## Role policy Roles are server-derived templates composed from permissions/scopes. Token ownership, wallet connection, localStorage or subscription UI state cannot grant administrative authority. Platform-level `super_admin` is distinct from ordinary tenant/workspace administration and cannot be acquired through normal creator onboarding or wallet ownership. ## Normalized failures Core policy errors include: ``` UNAUTHENTICATED SESSION_EXPIRED ACCESS_DENIED WORKSPACE_ACCESS_DENIED SUBSCRIPTION_REQUIRED ENTITLEMENT_REQUIRED FEATURE_DISABLED ``` Clients may choose sign-in, upgrade, workspace-selection or feature-unavailable UX based on stable codes, but the server error class remains authoritative. ## Cache rules Context responses are private user/workspace state and must not be publicly cached. Use `private, no-store` semantics. Invalidate: * `/auth/context` after session/account/membership/role/permission/wallet-verification changes; * `/access/context` after any auth-context change plus route/resource policy, subscription, entitlement or feature changes; * `/saas/me` after membership, subscription/checkout reconciliation, entitlement, feature-flag and included-permission changes. ## Marketplace fee policy Marketplace fee policy is versioned and snapshot into historical commercial operations. ```http GET /api/v1/fees/marketplace GET /api/v1/admin/fees PUT /api/v1/admin/fees/marketplace ``` Reading policy requires the relevant fee-policy permission. Publishing Marketplace fee policy requires `super_admin`, an operation-scoped `Idempotency-Key`, recent verification where configured, audit logging and a new immutable policy version. Historical Marketplace quotes/orders retain the fee-policy, licensing and settlement snapshots used by the original operation. Settled commercial refunds are disabled. Corrective economic action requires an explicit authorized reversal/ledger workflow where policy permits it; it is never simulated by mutating historical settlement records. ## Administrative role changes ```http PATCH /api/v1/admin/accounts/:id/role ``` Role mutation is a privileged operation. It requires server-side authorization and audit logging and must invalidate affected authority/access projections. The browser cannot promote itself by editing client state, wallet metadata or subscription fields. ## Balances Balance endpoints distinguish a factual provider-returned zero from unavailable provider state. Missing RPC/provider values are never converted into a fabricated zero. ## Money-moving operations Context resolution is only the beginning of the authorization chain: ``` 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 ``` No earlier state is a substitute for a later one. ## Administrative invariant ``` server-derived authority + explicit privileged permission + current policy + idempotent mutation + audit trail + durable state transition = valid administrative operation ``` --- # 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/session-roles-and-administrative-policy-api.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.