> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drpn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON-RPC

> Request and response shape for Darpan JSON-RPC calls.

All Darpan backend calls use `POST /rpc/json` with a JSON-RPC 2.0 envelope.

## Request shape

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "service.Name#Verb",
  "params": {}
}
```

The following calls `get#SessionInfo` from the Auth facade:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "facade.AuthFacadeServices.get#SessionInfo",
  "params": {}
}
```

## Required headers

Every call sends:

```http theme={null}
Content-Type: application/json
```

Which auth headers accompany it depends on the channel (see below): the browser-cookie
channel adds `X-CSRF-Token` plus the `darpan_login_key` session cookie; the header-token
channel adds `login_key` instead, with no CSRF token and no cookie.

## Authentication channels

Two channels exist. Which one applies is not ambiguous:

* **Browser app (canonical): HttpOnly cookie.** With cookie auth enabled, the app
  authenticates through the `darpan_login_key` HttpOnly cookie plus the CSRF token from
  `/apps/darpan/csrfToken`. No token is stored where page scripts can read it.
* **Integration callers and fallback: `login_key` header.** Non-browser clients — and
  browser deployments where credentialed CORS is unavailable — send the token returned by
  `login#Session` in the `login_key` request header. Keep the token in memory; never put it
  in query parameters.

The backend CORS end-state is an exact-origin allowlist with
`Access-Control-Allow-Credentials` for the app origins. A wildcard allowlist is an incident
posture, not a configuration.

## Success shape

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "ok": true
  }
}
```

## Error shape

Errors return an `error` object instead of `result`; facade business validation instead returns `result.ok: false` with `result.errors[]`. For the envelope, the code table, and the validation shape, see [Errors](/api-reference/errors).

## Contract versioning

The generated contract carries `info.x-darpan-contract-version`, decoupled from the
product release version. The policy is additive-only:

* **Non-breaking, no version bump:** new methods, new optional request parameters, new
  response fields.
* **Breaking, requires a conscious version bump:** removing a method, removing or renaming
  a parameter or response field, changing a field's type, or making a parameter newly
  required.

CI compares every pull request's contract against its base and fails on breaking changes
that arrive without a version bump.

Service-specific fields vary by method. They are documented from backend facade definitions and verified runtime responses.

For a catalog of available methods, see [Service catalog](/api-reference/service-catalog).