reference / federation api
Federation API
REST API for managing Kite federation peers, tokens, outbox state, and dead-letter replay. All endpoints require an admin API key.
Authentication
All federation API endpoints require an admin-scoped API key in the Authorization header:
Authorization: Bearer kite_admin_...
Peer management
Peers are the remote Kite instances you forward events to. Each peer has its own credentials, scope filter, and hop limit.
/api/federation/peersList all federation peers for your team.
Response
[{ "id": "uuid", "name": "instance-b", "status": "active",
"peer_hook_url": "https://...", "scopes": ["stripe.*"],
"max_hops": 3, "created_at": "..." }]/api/federation/peersRegister a new federation peer.
Request body
namestringHuman-readable name for this peer.peer_hook_urlstringURL to POST events to on the remote instance.outbound_tokenstringToken sent in HMAC header when posting to this peer.inbound_tokenstringToken expected from this peer when it posts to us.scopesstring[]optionalEvent type glob patterns. Default: ["*"].max_hopsintegeroptionalMaximum federation hops before dropping. Default: 3.Response
{ "id": "uuid", "name": "instance-b", "status": "active", ... }/api/federation/peers/:idGet a single peer by ID.
Response
{ "id": "uuid", "name": "instance-b", "status": "active", ... }/api/federation/peers/:idUpdate peer configuration (scopes, max_hops, status).
Request body
scopesstring[]optionalReplace event scope list.max_hopsintegeroptionalUpdate hop limit.statusstringoptional"active", "paused", or "revoked"./api/federation/peers/:idRemove a peer. Pending outbox entries for this peer are cancelled.
Token management
Federation tokens are HMAC signing keys used to authenticate server-to-server event delivery. Generate tokens before registering peers.
/api/federation/tokensList all federation tokens (labels only — raw tokens are shown once at creation).
Response
[{ "id": "uuid", "label": "peer-b-outbound", "created_at": "..." }]/api/federation/tokensGenerate a new federation token.
Request body
labelstringHuman-readable label.Response
{ "id": "uuid", "label": "...", "token": "kite_fed_..." }/api/federation/tokens/:idRevoke a federation token. Active peers using this token will start failing immediately.
Outbox & dead-letter
The federation outbox is a Postgres-backed queue of pending event deliveries. Each entry tracks delivery attempts, retry schedule, and final status. Dead-letter entries can be replayed manually after fixing a peer configuration issue.
Outbox entry status values
pendingAwaiting delivery or retrydeliveredSuccessfully delivered to peerfailedLast attempt failed; will retrydead10+ failed attempts; requires manual replay/api/federation/outboxList outbox entries. Filter by peer, status, or date range.
Response
{ "entries": [...], "total": 0 }/api/federation/outbox/:idGet a single outbox entry with full delivery attempt history.
Response
{ "id": 123, "peer_id": "uuid", "event_id": "...", "status": "pending",
"attempts": 2, "next_attempt_at": "...", "deliveries": [...] }/api/federation/peers/:id/replay-deadRe-queue dead-letter entries for this peer for immediate retry.
Request body
limitintegeroptionalMax entries to replay. Default: 100.sincestringoptionalISO 8601 timestamp — only replay entries created after this time.Response
{ "queued": 42 }Federation health events
Kite emits internal CloudEvents on federation anomalies. Subscribe to these on your instance's kite source to build alerting and observability.
| Event type | When emitted | data fields |
|---|---|---|
kite.federation.delivery_failed | An outbox entry is dead-lettered after 10 failed attempts. | { peer_id, event_id, attempts, last_error } |
kite.federation.peer_paused | A peer is automatically paused after sustained delivery failures. | { peer_id, peer_name, failure_count } |
kite.federation.loop_detected | An event was dropped because the receiving instance appeared in kitefedchain. | { event_id, chain, dropped_at_instance } |
kite.federation.hop_limit_exceeded | An event was dropped because kitefedhops reached max_hops. | { event_id, hops, max_hops, peer_id } |
Listen for federation health events
kite listen kite --filter 'type like "kite.federation.%"'
Trusted senders
Before Instance A can send events to Instance B, Instance B must register A as a trusted sender. This controls which instances are permitted to POST to your hook endpoint.
/api/federation/trusted-sendersList trusted senders for your team.
Response
[{ "id": "uuid", "name": "instance-a", "created_at": "..." }]/api/federation/trusted-sendersRegister a trusted sender.
Request body
namestringName for this sender.inbound_tokenstringToken this sender uses in its HMAC header.Response
{ "id": "uuid", "name": "instance-a" }/api/federation/trusted-senders/:idRemove a trusted sender. Events from this instance will be rejected with 401.