Every service credential has an explicit scope grant. The route must accept service authentication, the credential must hold the required scope, and its creator must still have organization membership and a workspace role allowed to perform the operation.
Use the smallest grant your integration needs. For a read-only market quality integration, start with scores:read. Creating a study and retrieving it needs both studies:write and studies:read. The same scope names apply to API keys and OAuth clients.
Available scopes#
All paths below are relative to /api/liquidity-studio/v2. Entries describe implemented route families and representative operations; the API reference gives each operation's exact schema and security requirement.
| Scope | Allowed service surface |
|---|---|
scores:read |
Read market-quality score resources under GET /scores |
studies:read |
Read study resources under GET /studies |
studies:write |
POST /studies, POST /sandbox/studies, and POST /studies/{id}/reports |
strategies:validate |
Read strategy resources; POST /strategies; POST /strategies/legacy-wrappers; POST /strategies/{id}/proposal-admissions |
policies:compile |
POST operations under /policy-intent-drafts, including deterministic draft compilation |
policies:check |
POST /policy-checks without policy activation |
proposals:read |
Read resources under GET /proposals and GET /proposal-comparisons |
proposals:prepare |
POST /proposals and POST /proposal-comparisons to prepare decision packets |
vaults:read |
Read qualified-vault resources under GET /vaults |
receipts:read |
Read receipts and execution attribution under GET /receipts and GET /attributions |
proof:read |
Read proof, passport, and artifact resources under GET /proof, GET /passports, and GET /artifacts |
alerts:read |
Read alert and anomaly resources under GET /alerts and GET /anomalies |
webhooks:manage |
Read webhook subscription resources and POST /webhooks to register a subscription |
Despite the webhooks:manage name, service authentication currently allows webhook GET routes and subscription creation only. Pause, revoke, delivery retry, and other administration routes require the authentication declared by that specific operation.
GET /strategies/{id}/evidence requires an interactive session because it returns combined strategy and full study evidence. A single strategy scope does not authorize the study data in that view.
Scopes do not grant execution authority#
Service credentials cannot approve decision packets, administer credentials, activate autonomy policies, submit issuer Safe transactions, or use an authority-bearing route outside the service allowlist. Possessing every available scope does not change that boundary. These workflows require the interactive role, reviewed evidence, and any release or Safe checks specified by the operation.
The app's saved-project, agent-run, treasury, organization, and workspace workflows are not automatically service-accessible because an SDK has a method for them. Generated SDKs cover the API contract; the endpoint's security requirement determines which authentication method can call it.
OAuth scope selection#
At token exchange, request a subset of the client's grant using a space-separated scope field:
scope=studies:read studies:writeOmitting the field uses the client's granted scopes. A token cannot expand the client's grant. Each bearer request checks that the client is active, unexpired, and still grants the token's scopes. See Authentication for issuance, expiry, rotation, and revocation.
Membership and role checks#
KlineO authenticates the credential within the organization named by x-klineo-organization-id, then checks the credential creator's current membership. The creator's role still limits the operation. Removing that membership prevents the service credential from accessing that organization's authenticated v2 routes.
For example, proposals:prepare allows entry to the preparatory route, but the route may still reject a role that cannot create the requested evidence. Treat 403 as a permissions problem to investigate rather than a request to add arbitrary scopes.
Service rate limits#
The service limiter maintains a budget per organization, credential, and required scope over a 900-second window. Default budgets are 1,000 requests for scopes ending in :read and 200 for other scopes; deployment configuration can change these values. A GET requiring strategies:validate uses that scope's budget, not a separate read budget.
Exhaustion returns 429 with LIQUIDITY_STUDIO_SERVICE_SCOPE_RATE_LIMITED and Retry-After: 900. An unavailable persistent limiter returns 503 and grants no request authority. Honor Retry-After and reuse the same mutation idempotency key when retrying an unchanged request. See Errors and retries.