Server SDKs

A server SDK is the library your backend uses to work with Centrifugo - as opposed to a client SDK, which runs in browsers and apps. It covers what a backend does with Centrifugo over HTTP, not only API calls:

• The server API: every method, Centrifugo PRO's included. The API is plain HTTP with JSON, so you can always call it directly, but an SDK takes care of what is easy to get wrong: retries which don't publish twice, broadcasts where some channels fail, timeouts.
• Connection tokens and subscription tokens, signed with HMAC, RSA, ECDSA or Ed25519 keys, with a JWKS endpoint for the public keys - and the endpoints your client SDK's connection and subscription token callbacks call.
• Shared poll signatures, and the endpoint client SDKs call for them.
• Proxy handlers: your backend's side of Centrifugo's HTTP proxy - connect, subscribe, publish, RPC, refresh and the rest - each answering with exactly what its proxy type can carry.

Not a real-time connection

Server SDKs call Centrifugo from your backend: they publish, manage channels and sign tokens, but don't hold a connection open to receive publications. To connect to Centrifugo and get publications in real time - from a browser, a mobile app, or a backend process which subscribes to channels - use a client real-time SDK: centrifuge-js, centrifuge-go, centrifuge-python, centrifuge-dart, centrifuge-swift, centrifuge-java, centrifuge-rust or centrifuge-csharp. For example, in Python, pycent publishes from your backend, and centrifuge-python subscribes as a client.

Official SDKs

Language	SDK	Install	Requires
Go	gocent	go get github.com/centrifugal/gocent/v4	Go 1.27
Python	pycent	pip install cent	Python 3.11
JavaScript, TypeScript	jscent	npm install jscent	Node.js 22, Deno 2, Bun 1.2, edge runtimes
PHP	phpcent	composer require centrifugal/phpcent	PHP 8.3
Ruby	rubycent	gem "cent", "~> 5.0"	Ruby 3.4
Rust	rustcent	cargo add cent	Rust 1.85
.NET	csharpcent	dotnet add package Centrifugal.Cent	.NET 8

All of them work with Centrifugo v6. The map and shared poll methods need Centrifugo v6.8.0 or newer, and the methods marked "Centrifugo PRO only" need Centrifugo PRO.

What every SDK does

The SDKs follow one specification, so they behave the same in every language - only the way a call is written is the language's own. Each SDK:

• Calls every server API method, Centrifugo PRO's included, with request and result types generated from Centrifugo's own API schema.
• Returns an error unless the call did everything asked. A broadcast or batch in which some parts failed is an error which still holds every part's outcome, so you can see which channels got the publication.
• Matches Centrifugo errors by code - unknown channel, not available, too many requests - and tells which errors a retry may fix.
• Retries safely. A publication is retried with the same idempotency_key, and a broadcast retry is sent only to the channels which have not got it yet.
• Bounds every call by a timeout - 10 seconds by default - which a call can shorten or replace.
• Checks a request before sending it: a missing required field or a payload which is not valid JSON fails at once, naming the field, rather than as a bad request from Centrifugo.
• Batches concurrent calls automatically, if you enable it, to cut the requests Centrifugo handles under load - never delaying a call while requests are below the limit you set.
• Reads paged results for you: history, map state and device lists are iterated a page at a time, each item with its stream position.
• Signs tokens: connection and subscription tokens with HMAC, RSA, ECDSA or Ed25519 keys, a JWKS endpoint for the public keys, and API tokens for Centrifugo PRO's JWKS authentication of the server API.
• Serves the endpoints client SDKs call for connection and subscription tokens and shared poll signatures.
• Answers the proxy: a handler per proxy type, which answers with exactly what the proxy type can carry.
• Writes commands for the async consumers, to put into an outbox table or a Kafka topic.

Each SDK's README has the details for its language, and its API reference documents every method.

A first publication

Go

client, err := gocent.New(gocent.Config{
	APIEndpoint: "http://localhost:8000/api",
	APIKey:      os.Getenv("CENTRIFUGO_API_KEY"),
})
if err != nil {
	log.Fatal(err)
}
res, err := client.Publish(ctx, gocent.PublishRequest{
	Channel: "news",
	Data:    jsontext.Value(`{"text":"hello"}`),
})
if err != nil {
	log.Fatal(err)
}
log.Printf("published at offset %d", res.Offset)

Python

import os
import cent

client = cent.Client("http://localhost:8000/api", api_key=os.environ["CENTRIFUGO_API_KEY"])

res = client.publish(channel="news", data={"text": "hello"})
print(f"published at offset {res.offset}")

JavaScript

import { Client } from 'jscent';

const client = new Client({ apiEndpoint: 'http://localhost:8000/api', apiKey: process.env.CENTRIFUGO_API_KEY });

const res = await client.publish({ channel: 'news', data: { text: 'hello' } });
console.log(`published at offset ${res.offset}`);

PHP

use Centrifugal\Phpcent\Client;

$client = new Client('http://localhost:8000/api', apiKey: (string) getenv('CENTRIFUGO_API_KEY'));

$res = $client->publish(channel: 'news', data: ['text' => 'hello']);
echo "published at offset {$res->offset}\n";

Ruby

require "cent"

client = Cent::Client.new(api_endpoint: "http://localhost:8000/api", api_key: ENV.fetch("CENTRIFUGO_API_KEY"))

res = client.publish(channel: "news", data: { text: "hello" })
puts "published at offset #{res.offset}"

Rust

use cent::{Client, Config, PublishRequest};
use serde_json::json;

let client = Client::new(
    Config::new("http://localhost:8000/api").api_key(std::env::var("CENTRIFUGO_API_KEY").unwrap()),
)?;
let data = cent::json(&json!({"text": "hello"}))?;
let res = client.publish(PublishRequest::new("news").data(data)).await?;
println!("published at offset {}", res.offset);

.NET

using Centrifugal.Cent;

await using var client = new CentClient(new CentClientOptions
{
    ApiEndpoint = "http://localhost:8000/api",
    ApiKey = apiKey,
});
var result = await client.PublishAsync("news", new { text = "hello" });
Console.WriteLine(result.Offset);

For AI coding agents

If you are an AI coding agent writing a backend which talks to Centrifugo, these are the points where generated code most often goes wrong:

• Use the SDK for the language rather than raw HTTP calls. It already handles the error model, timeouts and retries below.
• Retry a publication only with an idempotency_key, the same one on every attempt: an error does not mean nothing was published. A key built from an ID must name the event too - order-42-paid, not order-42.
• Don't retry a failed broadcast as a whole: it would publish twice into the channels which got it. Use the SDK's broadcast retry, which resends only to the channels which failed.
• Check every part of a broadcast or batch. An error from a broadcast may be partial - some channels got the publication - and the error holds each channel's outcome.
• A 404 from a method marked "Centrifugo PRO only" means the server is Centrifugo OSS, not that the endpoint is wrong.
• Put the API key in the X-API-Key header - the SDKs do - and never in a client-side token or the browser.
• Keep proxy handlers reachable by Centrifugo only: whoever can call them can claim to be any user.
• For streaming AI responses, see Real-time for AI apps: publish chunks in order, one call after another, not concurrently.

HTTP or GRPC

The server SDKs use the HTTP API. Centrifugo also has a GRPC API with the same methods, for which you generate a client from Centrifugo's Protobuf schema. HTTP is the default choice: with connections kept alive and calls batched automatically, its per-call cost is small, it needs no dependencies, and it works on every platform - edge runtimes included.

GRPC is worth it when:

• you publish at very high rates, and serializing JSON shows in your profiles: GRPC uses Protobuf;
• your payloads are binary: GRPC carries them as bytes, where the HTTP API takes them base64-encoded in b64data;
• you need the proxy streams, which only GRPC supports.

A generated GRPC client calls the methods, and nothing more: what the SDKs add - retries which don't publish twice, broadcast errors with each channel's outcome, Centrifugo errors matched by code, one timeout per call - you write yourself. The SDKs' token signing, client SDK endpoints and proxy handlers work the same alongside a GRPC client, as they don't depend on the API transport.

Community libraries

These server API libraries are made by the community. They are not part of the official set, and may not cover every method:

• katarinamolotova/javacent – HTTP API client for Java
• SocketSomeone/cent.js – API client for NodeJS
• sajjad-fatehi/CentriAgent – one more API client for NodeJS
• ismkdc/Centrifugo.AspNetCore – API client for ASP.NET Core
• devops-israel/crystalcent – API client for Crystal language
• Cyberguru1/rucent – HTTP API client for Rust