# Scopes and permissions

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:

```text
scope=studies:read studies:write
```

Omitting 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](/developers/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](/developers/errors/).