> ## Content Index
> Fetch the complete content index at: https://blog.protokol.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# Satellites: connect your own JSON-RPC service to a project
- URL: https://blog.protokol.io/satellites/
- Published: 2026-11-17T17:33:01.000Z
- Updated: 2026-11-17T19:14:52.000Z
- Description: Satellites connect a custom JSON-RPC service to your project without publishing to the marketplace, with versioned schemas, Dev/Live rollout, RBAC checks, health and logs.
- Author: Strahinja Djuric
- Tags: Engineering

Sometimes a workflow needs to call a service that only your team uses: a CRM, a pricing engine, an internal tool. Publishing it as a marketplace integration is more than you need.

A **satellite** is a project-level JSON-RPC integration that your team owns and configures. It is not a marketplace integration. It is visible only in the Developer section of the project where you created it (in the dashboard, Developer › Satellites), and only to users in that project.

## How a satellite is built

A satellite has two parts:

| Part           | Purpose                                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Template       | Operational metadata: ID, label, JSON-RPC endpoint URL, optional health check URL, optional logs URL, auth type and timeout. |
| Schema version | Versioned capabilities: permissions, JSON-RPC commands and workflow nodes.                                                   |

![The Create satellite form filled with example values: a CRM satellite with a JSON-RPC endpoint, a health check URL and bearer auth](https://blog.protokol.io/content/images/2026/11/01-create-satellite.png)  
*The Create satellite form: ID, endpoint, health check URL and auth type.*

The template records which schema version is active in each environment, in `dev_version` and `live_version`. Your service exposes **one** JSON-RPC endpoint over HTTP. You don't create a route per command: the schema maps each platform command name to a JSON-RPC method.

### A template

```json
{
  "id": "crm-satellite",
  "label": { "en_US": "CRM Satellite" },
  "jsonrpc_endpoint_url": "https://crm-satellite.example.com/jsonrpc",
  "health_check_url": "https://crm-satellite.example.com/health",
  "logs_url": "https://crm-satellite.example.com/logs",
  "auth_type": "bearer",
  "auth_config": { "secret": "dev-secret" },
  "timeout_ms": 30000
}

```

Two auth types are supported. With `bearer`, Protokol sends `Authorization: Bearer <secret>`. With `api_key`, it sends your chosen header (`auth_config.header_name`, required) with the secret as its value. Secrets are encrypted at rest, decrypted at runtime, and injected only when requests go to your service.

### A versioned schema

```json
{
  "schema_version": "2026-06-22.crm.v1",
  "permissions": [
    { "action": "execute", "label": { "en_US": "Execute CRM satellite commands" } }
  ],
  "jsonrpc_commands": [
    { "name": "echo", "method": "echo", "permission_action": "execute" },
    { "name": "uppercase", "method": "workflow.uppercase", "permission_action": "execute" }
  ],
  "workflownodes": [
    {
      "name": "satellite.crm.uppercase",
      "label": { "en_US": "Uppercase Text" },
      "command": "uppercase",
      "inputs": [{ "name": "text", "type": "string", "required": true }],
      "outputs": [{ "name": "uppercase", "type": "string" }]
    }
  ]
}

```

Only `schema_version` and `jsonrpc_commands` are required. Each command has a stable `name`, a JSON-RPC `method`, and an optional `permission_action` that defaults to the command name.

## Dev and Live rollout, and rollback

Deploying a schema version stores its `schema_version` string in `dev_version` or `live_version`. Rolling back is the same operation: deploy an older version to that environment. Protokol sends the active environment to your service in the `X-Env` header, so you can route to development or live behaviour on your side.

```bash
ptkl satellite deploy crm-satellite --schema-version 1.1.0 --target-env dev
ptkl satellite rollback crm-satellite --schema-version 1.0.0 --target-env live

```

Every request also carries the deployed `schema_version` in `params.satellite`. That lets one deployment of your service handle an old and a new schema during a rollout.

## Calling commands

From the SDK:

```js
import { Satellites } from '@ptkl/sdk/beta';

const satellites = new Satellites({
  token: process.env.PROJECT_API_TOKEN,
  env: 'dev',
});

const response = await satellites.execute('crm-satellite', 'echo', {
  inputs: { message: 'hello' },
});

```

From a workflow, add the satellite's **workflow node** to the canvas. Each node maps to one command, and running it calls `Satellites.execute()` for that command. Satellites provide workflow nodes, not workflow events or render events. From the command line, `ptkl satellite execute <id> <command>` does the same.

Satellites can also back the Resource Resolver. A PRN of the form `prn:satellite:<satellite_id>:<path>` is proxied to your command named `resolve_resource`.

## Permissions

The schema's permissions are exported into the platform's role system, where you assign them to roles. Protokol generates the key as `{action} satellite::{satellite_id}`, such as `execute satellite::crm-satellite`.

Protokol resolves authentication and authorization **before** it calls your service, and a command only runs if the permission it requires exists and is assigned. If you remove a permission in a later schema version, stale role assignments can be cleaned up later in the background, but runtime checks only allow commands whose permission currently exists and is assigned. Your service also receives the caller's identity in `X-Claims-Entity-*` headers and in `params.context`.

## Health and logs

If you set `health_check_url`, Protokol checks it every 60 seconds and shows the result in the Developer UI. If you set `logs_url`, the Developer UI loads logs from your service through Protokol, passing a `since` timestamp. `ptkl satellite logs <id>` fetches them from the CLI.

## The contract your service implements

The JSON-RPC contract is the reference for implementors. The essentials:

- **Request.** `POST` to your `jsonrpc_endpoint_url` with a JSON-RPC 2.0 body. Protokol never sends batches or notifications. The `id` is always a string.
- **Dispatch on `method`.** `params` has four keys: `inputs` (forwarded as the caller sent it, with no validation), `context`, `satellite` and `tenant`. Validate `inputs` yourself.
- **Scope by tenant.** `params.tenant.project_uuid` is your tenant boundary if one service backs several projects.
- **Respond with HTTP 200.** Put failures in the JSON-RPC `error` object. A non-2xx status is turned into an opaque failure and your `error` is never read. Protokol doesn't branch on error codes, so write `message` for a human.
- **No retries.** Each execution makes exactly one HTTP attempt, within `timeout_ms` (30 seconds if unset). The platform provides no idempotency, so dedupe on a key from `inputs` if a command isn't naturally idempotent.
- **Size.** Responses are read up to 10 MB. Return references rather than large payloads.
- **Authenticate requests.** Verification is a constant-time comparison of the shared secret. If no secret is configured, requests arrive unauthenticated, so reject those.

The health check is different: it is a `GET` with a 5-second timeout, sent **without** your secret, so keep that route outside your auth middleware and return nothing sensitive from it. Any `2xx` is healthy, and an unhealthy satellite is still called.

A minimal handler looks like this:

```js
app.post('/jsonrpc', async (req, res) => {
  if (!authorized(req)) {
    return res.status(401).json(rpcError(req.body?.id ?? null, -32600, 'unauthorized'));
  }
  const { id = null, method, params } = req.body ?? {};
  const handler = handlers[method];
  if (!handler) return res.json(rpcError(id, -32601, `unknown method: ${method}`));
  // run the handler, then return { jsonrpc: '2.0', id, result }
});

```

## A worked example

You want a workflow step that normalizes a contact name using your own service.

1. Register a template `crm-satellite` with your endpoint and a bearer secret.
2. Create schema version `2026-06-22.crm.v1` with the `uppercase` command and a workflow node for it.
3. Deploy it to `dev` and assign `execute satellite::crm-satellite` to the roles that should run it.
4. Add the node to a workflow and test it against Dev.
5. When it behaves, deploy the same version to `live`. If a later version misbehaves, roll `live` back to the earlier one.

## Learn more

The [Satellites guide](https://docs.protokol.io/platform/satellites/?ref=blog.protokol.io), the [JSON-RPC contract](https://docs.protokol.io/platform/satellite-rpc-contract/?ref=blog.protokol.io) (with a full reference server) and the [ptkl satellite reference](https://docs.protokol.io/toolkit/satellites/?ref=blog.protokol.io) cover the details. The [TypeScript SDK](https://docs.protokol.io/sdk/typescript/?ref=blog.protokol.io) page documents the client used to call them.