# Permissions and credentials

Klineo evaluates three distinct permissions: access to an organization, permission to perform an application workflow, and authority to sign an onchain action. An organization role or developer credential grants only its permitted application operations. Onchain authority belongs to the issuer Safe and the active contract policy.

## Organization scope

Send `x-klineo-organization-id` with organization-scoped requests. The value identifies the organization you intend to access. The backend checks current membership for the authenticated subject, validates the requested resource belongs to that organization, and applies the operation's role rules.

Being a member of one organization does not grant access to another. Reusing an ID, cursor, idempotency key, or resource reference from another organization cannot confer access. Organization creation and invitation acceptance use their own authenticated bootstrap workflows because an actor may not yet have organization membership.

Database row-level security provides an additional boundary for protected records. It does not replace API authorization, and integrations must not pass database service credentials to users.

## Interactive roles

The following table summarizes the core Liquidity Studio permission sets. V2 features also apply route-specific role and evidence requirements; a general role description does not guarantee access to every feature.

| Role | Principal capabilities | Authority boundary |
|---|---|---|
| `ORGANIZATION_OWNER` | Organization administration; vault creation, funding, pause and exit workflows; simulation and policy drafting; policy and proposal approvals; reporting, billing, and operations. | Application ownership does not make the actor an issuer Safe signer. |
| `TREASURY_ADMIN` | Vault creation, funding, pause and exit workflows; simulations, policy drafts, proposals and proposal approval; billing reads. | Core permissions do not include policy approval or organization management. |
| `APPROVER` | Policy and proposal approval; incident acknowledgement; organization and vault reads. | Approval does not by itself submit or sign a Safe transaction. |
| `ANALYST` | Simulations, policy drafts, proposal preparation, report generation, and evidence-backed AI generation. | Cannot approve policies or proposals, fund vaults, or change organization authority. |
| `VIEWER` | Organization, vault, and permitted AI-output reads. | Does not mutate liquidity workflows. |
| `KLINEO_OPERATOR` | Authorized operational, eligibility, proposal submission and recovery workflows; reports, billing and internal operations. | Internal role assignment is separately checked; it does not grant issuer custody or Safe ownership. |
| `RISK_GUARDIAN` | Pause and risk-reduction workflows; incident management and operations reads. | Risk-reduction permission does not permit unrestricted risk expansion. |
| `INTERNAL_AUDITOR` | Organization, vault, billing, operations and permitted internal evidence reads. | Read access does not confer execution or approval authority. |

The current backend restricts developer credential administration to an organization owner or an authorized Klineo operator. Internal roles must also satisfy configured internal-role authority checks. Onchain guardian, executor, reconciler, and Safe owner addresses are configured independently from these application role names.

## Authentication methods

Interactive users authenticate with an email magic link and a server-verified session cookie. Use interactive authentication for authority-bearing actions that require a fresh ceremony. The current backend reports email magic-link authentication as assurance level `aal1`.

Supported service credentials on the v2 API are API keys and OAuth clients. A service request sends:

```http
Authorization: Bearer <API_KEY_OR_ACCESS_TOKEN>
x-klineo-organization-id: <ORGANIZATION_ID>
```

These are placeholders. Retrieve your real organization ID and provision credentials through an authorized interactive account. API keys are presented directly as bearer credentials. OAuth client secrets authenticate a client when obtaining an access token; they are not access tokens to send to ordinary resource routes. Issued OAuth access tokens have a one-hour lifetime and cannot request scopes outside their client grant.

Service authentication is scoped to the credential's organization and owning actor. The request still passes current membership, role, resource, and route checks. Revoked or expired credentials are rejected. OAuth requests also check the current credential grant, so a revoked client or narrowed scope invalidates access that exceeds the remaining grant.

## Available service scopes

| Scope | Supported purpose |
|---|---|
| `scores:read` | Read market-quality score resources. |
| `studies:read` | Read permitted study resources. |
| `studies:write` | Create studies, sandbox studies, and study report requests. |
| `strategies:validate` | Read and prepare supported strategy validation resources and proposal admission checks. |
| `policies:compile` | Prepare and compile supported policy-intent drafts. |
| `policies:check` | Check a policy without activating it. |
| `proposals:read` | Read proposals and proposal comparisons. |
| `proposals:prepare` | Prepare proposals and comparisons. |
| `vaults:read` | Read permitted vault resources. |
| `receipts:read` | Read receipts and execution-attribution resources. |
| `proof:read` | Read permitted proof, passport, and artifact resources. |
| `alerts:read` | Read alerts and anomalies. |
| `webhooks:manage` | Read and create supported webhook subscriptions. |

A scope is a route-specific grant, not a wildcard over a resource family. Check the API operation's `x-klineo-required-service-scope` and authentication requirements. For example, a combined strategy-and-study evidence route requires an interactive session because either single service scope would expose evidence from the other family.

There is no service scope for vault funding, Safe signing, policy activation, unrestricted transaction broadcast, organization administration, credential administration, or authority expansion. Service credentials cannot call routes without an allowed service scope. AI workflows and other interactive-only resource families are not made accessible by a `studies:write` or `proposals:prepare` grant.

## Fresh authentication and reviewed intent

Sensitive administrative and authority-changing actions require a verified interactive authentication ceremony within ten minutes. Examples include membership changes, credential creation and rotation, Safe challenges and verification, policy approval, Safe bundle and submission workflows, public report publication, and operational repair.

The server derives ceremony time from verified session evidence. Your request body, local clock, bearer token, and organization role cannot assert that evidence.

When the API returns `LIQUIDITY_STUDIO_REAUTHENTICATION_REQUIRED`:

1. Complete the email magic-link sign-in flow.
2. Reopen and review the exact intended action and current evidence.
3. Check the operation's idempotency behavior and the definitive result of the original attempt before submitting again.

Credential creation and rotation store a recent-authentication `401` as a completed client failure in their one-time-secret mutation handler. Reusing that key after signing in again replays the same `401`. After this definitive failure, complete reauthentication, review the intended action and current resource version, and submit a renewed intent with a new key.

Authentication or service-scope rejection before a mutation handler does not store a completed mutation result. The ordinary v2 record mutation handler also leaves its recent-authentication rejection unrecorded. For those cases, an unchanged intent can retain its original key after access is restored. Follow the operation's contract rather than treating every `401` identically.

For a lost response, timeout, or transient failure, retain the original key and exact request while recovering the result; do not assume that a new key is safe. If the resource changed while you reauthenticated, obtain the latest version and review the changed intent. Do not automatically replace the resource version in an approval made against outdated policy, custody, or market evidence. See [authentication failures and stored results](/developers/idempotency/#authentication-failures-and-stored-results).

## Idempotency and concurrency

Mutating operations identify the actor, organization, request path and body, and applicable resource version. Supply `Idempotency-Key` on operations that require it and `If-Match` where the operation requires a reviewed resource version. The same key with a changed request can conflict rather than creating a second action. An in-progress identical request can return a retryable conflict.

Authorization is checked again when a stored mutation response is replayed. A key is not a bearer authorization token. Treat keys as request identifiers, keep them stable for an unchanged retry, and never use retry logic to bypass review or permissions.

## Credential lifecycle

Creation and rotation return secret material through a one-time response. Persist the secret immediately in your server's secret store. Do not assume an idempotent replay will reveal it again. Credential records retain verification hashes and display selectors rather than the full plaintext secret.

Use a separate credential for each integration and environment. Choose only the scopes it needs and configure expiry where practical. Rotate after suspected exposure and revoke unused credentials. Verify that the owning actor retains the membership and role needed by the integration; a credential does not create independent organization authority.

The backend enforces persistent budgets per credential and scope. A `429` response includes `Retry-After`; respect it and preserve the idempotency key for an unchanged mutation. Rate-limit storage or authentication outages return an unavailable response rather than granting authority without verification. Actual deployment budgets may vary, so use response headers rather than embedding a fixed request allowance in your client.

## Common authorization errors

| Response | Meaning | Next action |
|---|---|---|
| `401` authentication required or invalid | Session or service credential is missing, expired, or rejected. | Sign in or replace the credential; retain the reviewed intent. |
| `401` reauthentication required | Sensitive action lacks a recent verified ceremony. | Complete interactive reauthentication and review again. |
| `403` membership required | Authenticated actor has no current membership in the selected organization. | Select an authorized organization or obtain an invitation. |
| `403` service scope required | Credential lacks the operation's scope, or the route is interactive-only. | Use an appropriately scoped credential or authorized interactive account. |
| `403` forbidden | Current application role does not permit the action. | Ask an organization owner to review role assignment. |
| `409` authority not released | Release, policy, or execution evidence does not permit the requested authority. | Keep the workflow in its allowed planning or shadow state. |
| `429` scope rate limited | Credential exhausted the current scope budget. | Wait for `Retry-After` and retry safely. |
| `503` authentication or rate-limit unavailable | Required verification infrastructure is unavailable. | Retry after recovery; no authority was granted. |

Retain the nested error's code and correlation ID when troubleshooting. Share the correlation ID with authorized support; do not include the secret credential.

## Implementation references

The role map is maintained in `backend-skeleton/src/liquidity-studio/authorization.ts`. Canonical service scope rules are shared by the runtime and OpenAPI generation in `packages/liquidity-api/src/operatingSystemServiceScopes.ts`. Session and service authentication, recent-authentication guards, and organization membership checks are implemented by the backend. See [Security and trust](/trust/security) and [Contract architecture](/trust/contracts) for the independent execution boundary.