Control Plane

Documentation Index

Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt

Use this file to discover all available pages before exploring further.

The AlgoVoi Control Plane is the management backend for all tenant configuration and lifecycle operations. It owns the authoritative state for every tenant, their compliance status, their API credentials, their webhook destinations, and their payment authority configuration. The control plane is not involved in the per-payment verification path — that responsibility belongs to the gateway and facilitator — but every tenant capability that the gateway exercises (API key validation, KYC gating, trial balance enforcement, mandate lookup) is sourced from state owned by the control plane. The control plane runs co-located with the gateway and exposes 212 or more routes. It serves both the Dashboard React SPA at dash.algovoi.co.uk and a programmatic REST API available to tenants and admin operators.

---

​

Overview

---

​

Tenant onboarding flow

Tenant onboarding is a six-stage process that gates mainnet payment processing behind identity verification. The stages are sequential; each stage must complete successfully before the next becomes available. Stage 1 — Account creation. POST /cloud-signup/create accepts email, password, and display_name. The IP address of the signup request is synchronously screened against three threat signals: Tor exit node lists, SpamHaus blocklists, and MaxMind GeoIP country classification. If the IP fails screening, registration is rejected before any account record is created. Stage 2 — Email verification. A time-limited verification token is sent to the submitted email address. The account is created but remains in inactive status until POST /cloud-signup/verify-email is called with the token. Unverified accounts cannot authenticate. Stage 3 — KYC document submission. After email verification, the tenant submits identity documents via POST /v1/kyc/submit. Accepted document types are passport, driving_licence, and national_id. A selfie image must accompany any identity document. All uploaded files are encrypted at rest immediately on receipt using the platform’s document encryption key before being written to persistent storage. The plaintext file is never written to disk. Stage 4 — KYC decision. For individual and sole_trader account types, KYC is evaluated by automated document verification (OCR Tier 1) and auto-approved if document quality and consistency checks pass. For company account types, the submission lands in the MLRO review queue and requires manual review by an admin operator. The tenant receives a kyc.approved or kyc.rejected webhook event when the decision is made. Stage 5 — Mainnet activation. On KYC approval, mainnet_active is set to true and trial_balance_usd is credited with 100000000 microunits ($1,000.00 USD equivalent). The tenant can now process live payments on mainnet. The trial balance decrements on each verified mainnet payment; when trial_exhausted becomes true, continued live payments require a paid plan. Stage 6 — KYB (conditional). Company tenants or tenants whose risk scoring produces an elevated risk tier receive a KYB (Know Your Business) requirement. POST /v1/kyb/submit accepts company registration documents, beneficial owner declarations, and proof of address. KYB documents are encrypted with a separate key family, isolated from the platform key and the KYC key. KYB is evaluated by the MLRO queue regardless of company size.

---

​

Tenant data model

​

Risk tier effects

Risk tier is set by the MLRO at any time. Tenants are not notified of their specific tier — they receive only the operational consequences (e.g. a KYB requirement prompt).

---

​

API key management

API keys authenticate tenant API calls to both the gateway and the control plane. Keys are created, scoped, and revoked through the control plane.

​

Key types

​

Key lifecycle endpoints

​

Key creation fields

The full key value is returned once in the creation response and never again. The control plane stores only a SHA-256 hash of the key. If the key value is lost, it must be revoked and a new key created. Multi-key rotation. A tenant may hold multiple active keys simultaneously. During a rotation, the old key remains valid while the new key is adopted across integrations. The old key should be explicitly revoked via DELETE /v1/api-keys/{id} once migration is complete.

​

Admin scopes

Admin keys (algv_admin_) have access to 14 scopes not available to standard keys:

---

​

Webhook configuration

Tenants register webhook endpoints to receive platform events. The control plane manages endpoint registration, screening, and delivery.

​

Endpoint registration

POST /v1/webhooks URL screening at registration. Before a webhook URL is saved, the control plane evaluates it against:

• SSRF guard: private IP ranges, localhost, and link-local addresses are rejected
• 7 threat-intel feeds: same feeds used for IP screening at signup
• DNS resolution: the hostname must resolve at registration time

DNS-rebinding guard at delivery. At every webhook delivery attempt, the destination hostname is re-resolved. If the resolved IP has changed to a private range since registration, the delivery is aborted and a webhook.delivery_blocked.dns_rebinding event is recorded on the endpoint.

​

Delivery retry schedule

After 9 failed attempts the endpoint is marked degraded. The tenant receives a webhook.endpoint.degraded notification to the next reachable endpoint (or email if all endpoints are degraded). Endpoints can be re-activated via PATCH /v1/webhooks/{id} with { "active": true }.

​

Webhook event catalog

The full set of 18 subscribable event types:

---

​

Mandate lifecycle

A mandate represents an on-chain payment authority granted by a payer to a merchant. The control plane owns the mandate record; the gateway and Recurr service read from it.

​

Mandate states

​

State transitions

​

Cancellation reasons

​

Mandate data model

​

EMR safeguards

The following safeguards are enforced at the control plane level on all mandates, regardless of the stated cap. They cannot be overridden by tenant configuration: These limits implement EMR 2011 regulation 20-21 safeguarding requirements for e-money and agent-initiated payment flows.

---

​

Recurring payment authorities (Tier 2)

Recurring authorities are standing payment permissions that allow AI agents or automated systems to initiate time-based pulls against a payer wallet without per-pull interaction. They are managed by the control plane and executed by the recurring payment engine.

​

Authority data model

​

Authority lifecycle

POST /v1/recurring-authorities creates a new authority in pending_signature state. The on-chain wallet signature must be obtained and confirmed before the authority moves to active. Signature confirmation follows the same flow as mandate activation — the gateway detects the on-chain signature and updates the authority status. Once active, the Recurr service executes pulls on the schedule defined by period_unit and period_count. Each pull produces a recurring.pull_executed or recurring.pull_failed webhook event. Manual pull. POST /v1/recurring-authorities/{id}/execute triggers an immediate out-of-schedule pull. This supports catch-up after a missed cycle or proration scenarios. The manual pull respects all the same caps as a scheduled pull. Pause and resume. PATCH /v1/recurring-authorities/{id} with { "status": "paused" } suspends scheduled pulls without requiring a new on-chain signature. { "status": "active" } resumes from the next scheduled cycle. The authority’s next_execution_at is recalculated on resume. Exhaustion. When total_pulled_microunits reaches lifetime_cap_microunits, the authority status is set to exhausted and no further pulls are attempted. The tenant receives a recurring.pull_failed event with reason lifetime_cap_reached.

---

​

MLRO admin queue

The MLRO (Money Laundering Reporting Officer) queue is the manual review surface for KYC and KYB submissions that require human examination. It is accessible only to users authenticated with an admin-scoped key carrying the relevant admin scopes.

​

KYC queue

GET /admin/kyc/queue returns all pending KYC submissions sorted by submitted_at. Each queue item includes: POST /admin/kyc/{tenant_id}/approve approves the submission and triggers mainnet activation. POST /admin/kyc/{tenant_id}/reject rejects with a required reason field. Both actions generate the corresponding webhook event to the tenant.

​

KYB queue

GET /admin/kyb/queue returns pending KYB submissions. KYB submissions always require manual review regardless of company size. The queue item includes beneficial owner declarations, company registration document references, and a risk score from the KYB screening pipeline. POST /admin/kyb/{tenant_id}/approve and POST /admin/kyb/{tenant_id}/reject follow the same pattern as KYC decisions. A KYB rejection does not affect the tenant’s mainnet_active status if it was already true; it applies a risk_tier upgrade to elevated or high depending on the rejection grounds.

​

Admin event log

All admin actions (KYC decisions, KYB decisions, risk tier overrides, mandate cancellations, trial balance adjustments) are appended to an immutable admin event log. GET /admin/events returns a paginated log sortable by timestamp. Each event records actor (admin key ID), action, target_tenant_id, before_state, after_state, and timestamp.

---

​

KYC and KYB encryption

All identity documents are encrypted before being written to any persistent storage layer. The encryption architecture uses three separate key families to ensure that a compromise of one key does not expose documents of a different class.

​

Key families

Every encrypted file carries an in-band header encoding the key family identifier. The decryption loader verifies the header matches the expected key family before attempting decryption. A file presented to the wrong loader is rejected before any decryption is attempted.

​

Zero-downtime key rotation

The platform supports zero-downtime key rotation. At any point a key family may have two active tokens: the current token (used for all new encryptions) and the previous token (honoured for decryption of files encrypted under the old key). Background re-encryption of existing files completes silently without any application-layer downtime. Once re-encryption is complete, the old token is retired from the decryption stack.

​

Key loss consequences

Loss of any document encryption key renders the associated encrypted files irrecoverable. Key material is stored outside the codebase in a secrets store isolated from the application layer.

---

​

Dashboard API surface

The control plane’s API is the backend for the Dashboard React SPA. The dashboard surfaces the following management areas:

---

​

Trial offer

Newly mainnet-activated tenants receive a trial credit of 100000000 microunits ($1,000.00 USD equivalent). The trial balance is decremented by the USD-equivalent of each verified mainnet payment. When the balance reaches zero, trial_exhausted is set to true. Tenants on the trial plan with an exhausted balance must upgrade to standard or enterprise to continue live payment processing. Trial balance state is read by the gateway on every payment verification request. If trial_exhausted is true and plan is trial, the gateway returns 402 Payment Required with error code trial_exhausted before dispatching to the facilitator. The trial offer does not apply to testnet payments. Testnet payments do not consume trial balance and do not create audit chain entries.

---

​

Recurr service integration

The recurring payment engine reads recurring authority schedules from the control plane database. It is responsible for:

• Evaluating which authorities have a next_execution_at in the past and are in active status
• Submitting pull transactions to the relevant chain
• Updating next_execution_at and total_pulled_microunits after each successful pull
• Emitting recurring.pull_executed or recurring.pull_failed events

The Recurr service does not expose an external HTTP API. It is triggered on a schedule and interacts with the control plane via database reads and writes. Manual pull requests from the POST /v1/recurring-authorities/{id}/execute endpoint are queued in the database and picked up by the Recurr service at its next polling interval. The recurring payment engine operates across all 7 supported chains. Pull execution on EVM chains (Base, Tempo) requires funded hot wallets.