> ## Documentation Index > Fetch the complete documentation index at: https://docs.usesynth.ai/llms.txt > Use this file to discover all available pages before exploring further. # account # `synth_ai.research.account` `client.research.account` — org account, billing, usage, and BYOK reads. These backend routes live under `/api/v1` (and `/api/members`), not under `/smr`, so this namespace calls them through the session client's internal `_request_json` layer, which applies the same base URL and `Authorization: Bearer ` header as every other SDK call. Mutations are limited to BYOK key management and `subscription.cancel`. ## Classes ### `AccountBalance` Typed `BalanceResponse` (org\_id, balance\_cents, balance\_dollars). **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> AccountBalance ``` ### `AccountTierLimits` Typed `TierLimitsResponse` (tier name plus its limits payload). **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> AccountTierLimits ``` ### `AccountByokStatus` Typed BYOK status (byok\_enabled, plan\_type, provider key coverage). **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> AccountByokStatus ``` ### `AccountReadinessCta` Typed `AccountReadinessCta` (call-to-action for a failing check). **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> AccountReadinessCta ``` ### `AccountReadinessCheck` Typed `AccountReadinessCheck` (one readiness gate with optional CTA). **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> AccountReadinessCheck ``` ### `AccountReadiness` Typed `AccountReadinessResponse` (org-level launch readiness with CTAs). **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> AccountReadiness ``` ### `AccountIdentity` Typed `MeResponse` (org and user resolution for the API key). **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> AccountIdentity ``` ### `ResearchAccountBalanceAPI` Org credit balance and usage summary. **Methods:** #### `get` ```python theme={null} get(self) -> AccountBalance ``` Read the current credit balance. Backend route: `GET /api/v1/balance/current`. #### `usage` ```python theme={null} usage(self) -> dict[str, Any] ``` Read the token/GPU usage summary. Backend route: `GET /api/v1/balance/usage`. ### `ResearchAccountCreditsAPI` Credits ledger reads. **Methods:** #### `transactions` ```python theme={null} transactions(self) -> dict[str, Any] ``` List purchase/usage transactions, most recent first. Backend route: `GET /api/v1/credits/transactions` (query `cursor`, `limit`). ### `ResearchAccountTiersAPI` Default rate limits per subscription tier. **Methods:** #### `list` ```python theme={null} list(self) -> tuple[AccountTierLimits, ...] ``` List default limits for all tiers. Backend route: `GET /api/v1/usage/tiers`. #### `get` ```python theme={null} get(self, tier: str) -> AccountTierLimits ``` Read default limits for one tier. Backend route: `GET /api/v1/usage/tiers/{tier}`. ### `ResearchAccountByokAPI` Bring-your-own-key provider key management. **Methods:** #### `list` ```python theme={null} list(self) -> dict[str, Any] ``` List stored provider key metadata. Backend route: `GET /api/v1/byok/keys`. #### `create` ```python theme={null} create(self) -> dict[str, Any] ``` Store a provider key (ciphertext encrypted with `crypto.public_key`). Backend route: `POST /api/v1/byok/keys`. #### `get` ```python theme={null} get(self, provider: str) -> dict[str, Any] ``` Read stored key metadata for one provider. Backend route: `GET /api/v1/byok/keys/{provider}`. #### `delete` ```python theme={null} delete(self, provider: str) -> dict[str, Any] ``` Delete the stored key for one provider. Backend route: `DELETE /api/v1/byok/keys/{provider}`. #### `validate` ```python theme={null} validate(self, provider: str) -> dict[str, Any] ``` Validate the stored key against the provider's API. Backend route: `POST /api/v1/byok/keys/{provider}/validate`. #### `status` ```python theme={null} status(self) -> AccountByokStatus ``` Read BYOK enablement and provider key coverage. Backend route: `GET /api/v1/byok/status`. ### `ApiKeyRedactedRow` Typed redacted key row (`prefix` + `last4` only; never the secret). **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> ApiKeyRedactedRow ``` ### `MintedApiKey` ONE-TIME mint/rotate result. `key` is the full `sk_synth_user_...` secret and is shown exactly once — the backend never returns it again (listings are redacted). Store it immediately; treat this object as sensitive material. **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> MintedApiKey ``` ### `ApiKeyDeactivated` Typed delete result (soft deactivation; the row is kept inactive). **Methods:** #### `from_wire` ```python theme={null} from_wire(cls, payload: object) -> ApiKeyDeactivated ``` ### `ResearchAccountKeysAPI` Synth API-key lifecycle (list redacted, mint, rotate, deactivate). Requires backend routes `/api/v1/auth/keys` (backend PR feat/api-key-lifecycle-routes-20260720); the caller's API key is the principal, and every operation is scoped to that key's (user, org). **Methods:** #### `list` ```python theme={null} list(self) -> tuple[ApiKeyRedactedRow, ...] ``` List the caller's active keys, redacted (prefix + last4 only). Backend route: `GET /api/v1/auth/keys`. #### `create` ```python theme={null} create(self) -> MintedApiKey ``` Mint a new key; the full secret is returned exactly once. Backend route: `POST /api/v1/auth/keys`. Returns 409 if an active key already exists (use :meth:`rotate`). `name` is refused by the backend today (no name column); pass it only once naming ships. #### `rotate` ```python theme={null} rotate(self, key_id: str) -> MintedApiKey ``` Rotate: deactivate `key_id` and mint a replacement. The old secret stops validating within the backend auth-cache TTL. Backend route: `POST /api/v1/auth/keys/{key_id}/rotate`. The new secret is returned exactly once. #### `delete` ```python theme={null} delete(self, key_id: str) -> ApiKeyDeactivated ``` Deactivate `key_id` (soft delete; the backend keeps the row inactive). Backend route: `DELETE /api/v1/auth/keys/{key_id}`. ### `ResearchAccountMembersAPI` Org member listing. **Methods:** #### `list` ```python theme={null} list(self) -> dict[str, Any] ``` List org members with app-user details. Backend route: `GET /api/members` (mounted with the `/api` prefix, not `/api/v1`; query `limit`, `offset`). ### `ResearchAccountSubscriptionAPI` Subscription lifecycle (cancel only). **Methods:** #### `cancel` ```python theme={null} cancel(self) -> dict[str, Any] ``` Cancel the subscription at the end of the current billing period. Backend route: `POST /api/v1/subscription/cancel`. ### `ResearchAccountCryptoAPI` Public-key material for client-side key encryption. **Methods:** #### `public_key` ```python theme={null} public_key(self) -> dict[str, Any] ``` Read the app public key used to encrypt BYOK keys. Backend route: `GET /api/v1/crypto/public-key`. ### `ResearchAccountAPI` Org account namespace: balance, credits, usage, BYOK, members, identity. **Methods:** #### `balance` ```python theme={null} balance(self) -> ResearchAccountBalanceAPI ``` Org credit balance and usage summary. #### `credits` ```python theme={null} credits(self) -> ResearchAccountCreditsAPI ``` Credits ledger transactions. #### `tiers` ```python theme={null} tiers(self) -> ResearchAccountTiersAPI ``` Default per-tier rate limits. #### `byok` ```python theme={null} byok(self) -> ResearchAccountByokAPI ``` Provider key (BYOK) management. #### `keys` ```python theme={null} keys(self) -> ResearchAccountKeysAPI ``` Synth API-key lifecycle (list redacted / mint / rotate / deactivate). #### `members` ```python theme={null} members(self) -> ResearchAccountMembersAPI ``` Org member listing. #### `subscription` ```python theme={null} subscription(self) -> ResearchAccountSubscriptionAPI ``` Subscription lifecycle (cancel). #### `crypto` ```python theme={null} crypto(self) -> ResearchAccountCryptoAPI ``` Public-key material for BYOK encryption. #### `usage` ```python theme={null} usage(self) -> dict[str, Any] ``` Read current org usage counters. Backend route: `GET /api/v1/usage`. #### `user_limits` ```python theme={null} user_limits(self) -> dict[str, Any] ``` Read effective limits for the authenticated user. Backend route: `GET /api/v1/usage/user-limits`. #### `overview` ```python theme={null} overview(self) -> dict[str, Any] ``` Read the entitlements + usage + spend overview. Backend route: `GET /api/v1/usage/overview` (query `days` 1-365, `include_projects`). #### `readiness` ```python theme={null} readiness(self) -> AccountReadiness ``` Read org account readiness checks (balance, runway, tier headroom, BYOK). Backend route: `GET /api/v1/account/readiness`. #### `me` ```python theme={null} me(self) -> AccountIdentity ``` Resolve the org/user identity for the API key. Backend route: `GET /api/v1/me`.