---
title: 7. Onboarding
tags: [Part 1]

---

# 7. Onboarding

> Connected Services Framework (CSF) — Part 1: Framework — Version 2.0

## 7.1 Overview

The CSF uses a peer-sponsored onboarding model. There is no centralised registration authority. Instead, existing MAPs take responsibility for validating and onboarding new participants, ensuring quality and compliance without the cost and complexity of a central governing body.

A minimum of **two MAPs** is sufficient for a basic bilateral exchange. This eliminates the need for a "big bang" approach — MAPs and CPs can be onboarded incrementally.

## 7.2 Onboarding a New MAP

### 7.2.1 Sponsorship Framework

New MAPs are onboarded through a structured, multi-phase process guided by a **Sponsor MAP** — an existing, onboarded MAP identified via FIFO rotation. The candidate initiates contact: it discovers the **current designated Sponsor** either from the TAG-published sponsor-registration page (URL to be published by the TAG) or by reading any existing MAP's CP Registry and locating the entry with the most recent `nextSponsorUpdated` timestamp (see the standalone *MAP Onboarding & Testing Process* §3.4 for the detailed mechanism).

Key principles:

- **Next Sponsor MAP**: Uses `nextSponsor` — a forward pointer that says "when I accepted my engagement, I designated X as next." The current sponsor is simply the MAP with the most recent `nextSponsorUpdated` timestamp. No consensus, no propagation of a shared value — just read the most recent write.
- **Capped costs (sponsor fees are free by default)**: Sponsor MAPs are **not expected to charge** for onboarding another MAP. There is an option to charge a fee when significant time and effort is required, capped at **£3,000 + VAT** for a `traditional` (multi-CP) engagement and at **£350 + VAT** for a `single-cp` (MAP-of-1) engagement. The option exists because the CSF expects the Sponsor MAP to apply a **quality gate** — all checks and baseline testing completed to TAG standards. The actual fee is a negotiation between the Sponsor MAP and the new MAP based on how much support is required. A MAP is only charged **once** for onboarding, regardless of how many industry protocols it eventually carries. A set of **shared test endpoints** will be created over time to further reduce sponsoring effort and cost. See §7.4.5 for the `single-cp` fast-track.
- **Gatekeeper role**: The Sponsor MAP acts as a gatekeeper to the CSF network, ensuring operational performance and compliance.
- **Evolving criteria**: The TAG continuously updates entry criteria to reflect the latest maturity levels and address known issues identified through industry testing and operational working groups.

### 7.2.2 On-Ramp Process

The onboarding process follows five phases:

> **1. Select Sponsor MAP** → **2. Initial Assessment** → **3. Integration & Testing** → **4. Operational Validation** → **5. Full Operations**

#### Phase 1 — Sponsor MAP Selection and Agreement

- The new MAP identifies and selects an existing MAP as its sponsor (or is assigned one via rotation)
- The Sponsor MAP verifies the request is legitimate
- Both parties agree on technical, operational, and compliance criteria

#### Phase 2 — Initial Assessment and Registration

- The Sponsor MAP conducts a capability assessment covering technical readiness, security, and compliance
- The new MAP registers essential details: endpoint URLs, PKI credentials, and directory synchronisation preferences

#### Phase 3 — Integration and Testing

- Secure communication channels are established using OAuth 2.0 and PKI
- Credentials at this stage provide **provisional/restricted access** — directory information should contain limited, obfuscated data to prevent disclosure of client information until testing is complete
- Testing verifies secure, authenticated message exchanges and directory synchronisation
- Once basic connectivity is proven, access levels are raised to **test** — the directory will now contain information to facilitate test communications (with CP consent or using test CPs)

#### Phase 4 — Operational Validation

- The Sponsor MAP verifies adherence to operational requirements: message delivery reliability, retry mechanisms, and SLA compliance
- Validation tests ensure interoperability with other MAPs and CPs
- Each other MAP performs additional sanity testing as they establish their own OAuth 2.0 connections with the new MAP
- A **72-hour soak** under projected production load is the default exit gate (see the standalone *MAP Onboarding & Testing Process* §6 Phase 4 and §9 Exit Criteria #2). The soak is **relaxed** for `single-cp` (MAP-of-1) engagements — see §7.4.9.

#### Phase 5 — Full Operations

- The Sponsor MAP formally approves the onboarding and notifies all other MAPs
- Connectivity is upgraded to **full access**
- The new MAP freely shares its complete CP Registry with other MAPs
- The new MAP commences independent, full operational integration

> The detailed testing process, entry criteria, and exit criteria are set out in the separate "New MAP Onboarding & Testing Process" document maintained by the TAG.

## 7.3 Onboarding a CP

CP onboarding is a commercial matter between the CP and its chosen MAP. The CSF does not prescribe how MAPs select or charge their CPs. However, the CSF requires certain steps to be completed before a CP can exchange messages:

### 7.3.1 MAP Responsibilities

1. **Allocate a unique RCPID** — A UUIDv4 identifier, verified against the directory to prevent collisions (see [RCPID Management](08-rcpid-management.md))
2. **Generate PKI key pair** — Create the public/private key pair for the CP
3. **Guide DNS setup** — Assist the CP in creating the two required DNS TXT records:
   - `[RCPID]._domainkey.[cp-domain]` — containing the public key
   - `[RCPID]._mapkey.[cp-domain]` — containing the MAP's message endpoint URL
4. **Collect customer data assets** — Ensure the MAP has sufficient data to perform timely Switch Match responses without relying on the CP being online
5. **Validate compliance** — Ensure the CP meets the requirements of the industry process they wish to participate in
6. **Publish in registry** — Add the CP to the MAP's registry with all mandatory fields

### 7.3.2 When a CP Can Exchange Messages

No messages can be exchanged until other MAPs verify that the CP is correctly associated with the MAP in its directory. This verification happens automatically when MAPs pull the updated registry and cross-reference it against the CP's DNS records.

A MAP can register a new CP and advertise it to other MAPs **within seconds**. However, the CP controls when it is ready to exchange by managing its DNS entries and service status (ACTIVE, TEST, SUSPENDED).

## 7.4 MAP-of-1 Onboarding (incl. TOTSCo → CSF Migration)

### 7.4.1 Definition and scope

A **MAP of 1** is a CP that operates the full MAP stack for its own brand: OAuth 2.0 token endpoint, Letterbox, CP Registry / Directory API, DKIM signing, and the CP's own `_domainkey` / `_mapkey` DNS records. The CP is a CSF peer to every other MAP and pays no transport fees to a third party. This section sets out the onboarding path **specifically for** a CP that wishes to take on the MAP role for itself — and in particular for the common case of a CP currently using **TOTSCo for SforB** (and / or for niche bilateral exchanges, or other non-OTS protocols) who wishes to **move that traffic to the CSF as their transport**.

> **OTS is out of scope of this migration.** OTS (One Touch Switch — residential switching) is **mandated by Ofcom to use TOTSCo as the single industry platform**. A CP that operates OTS in the UK MUST continue to use TOTSCo for that traffic. The §7.4 migration applies to **SforB** and other **non-OTS** protocols only — for example niche bilateral exchanges between CPs, or future industry protocols if and when the TAG adds them to the CSF baseline (see §7.4.10). A CP that currently uses TOTSCo for both OTS and SforB can move its **SforB** traffic to a CSF MAP-of-1 while **continuing OTS via TOTSCo unchanged**; the two are operationally independent at both the transport layer and the directory layer.

This section is in addition to §7.2 (sponsor-driven multi-CP MAP onboarding) and §7.3 (CP onboarding by an existing MAP). The technical onboarding mechanism is the **same five-phase on-ramp** as §7.2 — the differences are scope, fee guidance, soak relaxation, and the cutover story.

### 7.4.2 Strategic context — the CP remains in control

The CSF is the open-standard transport for SforB (and over time other industry protocols). It is the **bit pipe** (see [Definitions](../standalone/definitions.md)) for exchanging messages between CPs — a network provider that simply moves data without adding value or examining content. The CP — or MAP of 1 — remains in **direct control of its own customer relationship at all times**: end-consumer data, sales, support, billing, in-flight order state, and all CRM live with the CP, not with the transport. The transport (CSF or TOTSCo) carries the JAM-envelope messages; nothing more.

This is the central reader takeaway: a TOTSCo subscriber moving to the CSF as a MAP of 1 is **changing transport, not changing business**. The CP's brand, customers, **SORs (Switch Order References)** and ServiceIdentities are unaffected by the transport switch. The risk of the move is therefore low — provided the CP is in full operational control of its customer relationship before the cutover begins.

> **Brand uniqueness (industry constraint).** The SforB industry process supports a CP brand appearing **once** in the industry directory. This is not a CSF transport rule — it is a property of the industry-process layer (SforB / OTS) above the transport. The practical consequence is that a CP migrating from TOTSCo to a CSF MAP-of-1 **cannot dual-run** the same brand on both directories simultaneously; the move must be a **planned cutover** (see §7.4.7). The exception is during a brand change — e.g. as part of a merger or rebrand — where the new brand is a new directory entry and the old brand is consolidated under the §8.3 process.

### 7.4.3 Decision tree — "Should I become a MAP of 1?"

A CP considering self-serve operation on the CSF SHOULD work through the following:

| # | Factor | "Yes" if… |
|---|---|---|
| 1 | **Technical capability** | The CP can run TLS 1.3, OAuth 2.0 (client credentials), DKIM signing (RSA or Ed25519, using existing libraries — see §7.4.10), JSON registry serving, and CP-controlled DNS for the `_domainkey` and `_mapkey` records. |
| 2 | **Infrastructure overlap** | Most of the above (OAuth, DNS, TLS, JSON handling, message-queue and retry) is **already** running in the CP's existing TOTSCo integration — the increment for a MAP-of-1 is small. |
| 3 | **DKIM signing readiness** | The CP can integrate a DKIM signing library (RFC 6376 reference implementations exist for Java, .NET, Go, Python, Node, etc. — see §12 Tooling Reference in the standalone handbook). This is a one-off software change, not a recurring cost. |
| 4 | **Volume and business case** | The CP's annual TOTSCo subscription + unit charges exceed the CP's projected one-off MAP-of-1 build cost over a payback window the CP regards as acceptable. (See §7.4.10.) |
| 5 | **On-call cover** | The CP has, or can establish, the 24×7 incident-response posture required by §9 (Operational Excellence) and the SforB SLAs. |
| 6 | **Routing footprint** | The CP knows which other MAPs (or HMAPs like TOTSCo) it needs to exchange with, and is prepared to complete the bilateral tests for those it adds beyond the Sponsor MAP. |

If the CP cannot meet factor 1 today but expects to in the medium term, an interim **CP-onboarding-with-a-CSF-MAP** path (§7.3) is the safer choice; the CP can transition to MAP-of-1 later via §8.2 mechanisms. If the CP cannot meet factor 5 either, MAP-of-1 is not appropriate and a managed-MAP relationship should continue.

### 7.4.4 Pre-migration capability checklist

Before approaching a Sponsor MAP, the candidate CP SHOULD verify:

- [ ] **DNS zone control** — the CP controls the DNS zone(s) in which `[RCPID]._domainkey.[cp-domain]` and `[RCPID]._mapkey.[cp-domain]` will live (or has it under independent commercial control — see §6.5 best practice "keep DNS independent of the MAP").
- [ ] **TLS 1.3 endpoint capability** — the CP has, or can stand up, public HTTPS endpoints (OAuth token URL, Letterbox URL, Directory API URL, Service Status URL).
- [ ] **OAuth 2.0 IdP** — the CP can issue and validate client-credentials bearer tokens. Most CPs already operate one for their TOTSCo integration.
- [ ] **DKIM signing** — the CP can integrate a DKIM signing library and produce a CSF-format `X-CSF-SIGNATURE` header that passes against the public NowYoYo PKI Test Harness.
- [ ] **JSON registry** — the CP can publish a CP Registry that validates against the §5 Directory API schema.
- [ ] **Monitoring and on-call** — the CP has alerting, logging, and an on-call rota suitable for SforB SLAs.
- [ ] **CRM authority** — the CP's own CRM is the authoritative source of customer state (so the transport change does not depend on the outgoing hub).
- [ ] **In-flight order list** — the CP can enumerate the in-flight orders open on its TOTSCo subscription as of the planned cutover date (used to plan §7.4.7).

### 7.4.5 Sponsor MAP programme — fast track for single-CP

Sponsor MAPs are **encouraged** to use the `single-cp` engagement type (tracked as `type: "single-cp"` in `sponsorship.active[]`, see the standalone handbook §3.4) as a positive industry-development offering. The CSF treats existing-MAP sponsorship of TOTSCo-subscriber CPs as a **first-class adoption mechanism**: it grows the open network, gives the sponsor commercial visibility with a new peer, and gives the candidate a low-friction route in.

Differences for a `single-cp` engagement:

| Aspect | Traditional sponsorship | `single-cp` sponsorship |
|---|---|---|
| Fee | Free by default; capped at **£3,000 + VAT** when significant support is required | Free by default; capped at **£350 + VAT** when significant support is required (the absolute ceiling — the reduced scope, single CP, no multi-tenant DKIM, smaller registry, typically keeps the actual negotiated fee well below the cap) |
| Phase 4 soak | 72 hours at projected production load | **Soak waived** for the single-CP MAP-of-1 case — see §7.4.9 |
| Bilateral ≥50% coverage in Phase 4 | Required | **Waived** — only the bilateral tests the candidate intends to route to are required (see §7.4.9) |
| Speed | Weeks to months | Days to weeks once exit gate is met |

This is not a quality compromise: the candidate must still pass §8.1 – §8.9 of the standalone handbook against the Sponsor MAP and the NowYoYo PKI harness. What's relaxed is the **production-scale validation step**, on the basis that a MAP-of-1 is **a CP managing its own transport — the operational risk is internalised by the CP** (per §7.4.2). The CP that runs the MAP-of-1 is, by construction, the same CP who carries the consequence of a defect.

### 7.4.6 Finding your Sponsor MAP

Two discovery paths are available to a candidate (including before joining the network):

1. **TAG-published registration page** (URL to be published by the TAG) — this is the **primary** entry point. The TAG publishes the current designated Sponsor MAP and their registration contact details on the public TAG website. Updated whenever the rotation advances.
2. **Directory bootstrap** (fallback) — read any existing MAP's CP Registry over HTTPS and locate the `sponsorship` entry with the most recent `nextSponsorUpdated`. This is the in-band mechanism documented in the standalone handbook §3.4 and the only mechanism available before the TAG website is live.

Once the current Sponsor MAP is identified, the candidate contacts the Sponsor MAP's `map/contact[]` registration entry (or the TAG page's registration link). The Sponsor MAP's own onboarding portal handles the rest (Phase 1 — see §7.2.2 and the handbook §6).

### 7.4.7 The cutover journey — big-bang, CP-controlled

Because the SforB industry directory supports a CP brand only once (§7.4.2 brand uniqueness), the move from TOTSCo to a CSF MAP-of-1 **MUST be a planned cutover** — there is no dual-running window for a single brand. The cutover is **CP-controlled** at every step. Five stages:

1. **Build** (CP timetable; typically weeks). The CP builds and tests its MAP-of-1 stack against the Sponsor MAP's Test Tenant. `map.status=TEST`. The CP's TOTSCo subscription is unaffected. Phases 1 – 3 of §7.2.2 complete.
2. **Exit-gate pass** (CP timetable). Baseline tests §8.1 – §8.9 (handbook) pass against the Sponsor MAP and the NowYoYo PKI harness; Phase 4 relaxations per §7.4.9 satisfied; Sponsor MAP issues Phase 5 approval.
3. **In-flight position** (CP decision). The CP chooses the in-flight policy for its open TOTSCo orders. **Two valid paths** — neither imposed by the framework; the CP picks based on volume and risk:
   - **Drain-first (preferred when feasible)** — the CP stops accepting new switch matches on TOTSCo, lets all open in-flight orders complete or cancel cleanly, then performs the cut with zero in-flight balance. Lower operational complexity at cutover; longer total elapsed time.
   - **CP-managed migration** — the CP cuts when ready and reconciles in-flight orders from its own CRM. SORs and ServiceIdentities **do not need to change** — the CP holds the customer relationship throughout and the transport change is invisible to the underlying business state. If TOTSCo can be persuaded to honour an `rcpidStatusRequest`-equivalent export, happy-path import via the MAP-of-1 applies; otherwise the CRM-reconstruction model from §8.2.4 (CP Emergency Migration unhappy path) applies. The CP carries the operational risk — which is appropriate because the CP is the party in control.
4. **Cutover (big-bang)**. The CP coordinates with TOTSCo to terminate the **TOTSCo SforB** directory entry for the brand as the new CSF MAP-of-1 directory entry goes live. If the same brand also operates OTS via TOTSCo, the **OTS directory entry is unaffected** and continues unchanged — OTS is Ofcom-mandated to TOTSCo (see §7.4.1) and is out of scope of this migration. **TTL pre-staging** is used on the CP's `_mapkey` and `_domainkey` to keep the observed outage to single-digit minutes (the standard enterprise DNS-change routine: lower the TTL ≥24h before the cut-over, swap, then restore — see Part 2 §3 *PKI & DKIM Signing* for the canonical clause). The new CSF UUIDv4 RCPID is allocated per §7.4.8 — the legacy TOTSCo **SforB** `Rxxx` is retired (not migrated); any OTS `Rxxx` for the same brand on TOTSCo is independent and untouched.
5. **TOTSCo wind-down (SforB only)**. The CP closes its **TOTSCo SforB** participation per the TOTSCo contract terms (notice period, final invoice). If the CP continues to use TOTSCo for OTS, the **OTS subscription / participation continues unaffected** — only the SforB element is wound down. Audit retention rules per §9 apply.

> **The risk is low precisely because the CP is in control.** The CSF (and TOTSCo before it) is the transport, not the business. End-consumer relationships, SORs, ServiceIdentities, billing, support — all of these live in the CP's CRM and are unaffected by the cut.

### 7.4.8 RCPID allocation rule

A CSF MAP-of-1 is allocated a **new UUIDv4 RCPID** in the standard way (see §8 RCPID Management) — the legacy TOTSCo `Rxxx` 4-character RCPID is **not reused, not migrated, and not preserved as the CSF RCPID**. The two identifiers are independent.

For OTS-side historic reporting (post-cutover queries that reference the legacy `Rxxx`), the CP retains its TOTSCo records under TOTSCo's own retention regime; the CSF retention applies only to messages exchanged over the CSF.

### 7.4.9 Phase 4 relaxation for MAP-of-1

For `single-cp` (MAP-of-1) engagements, Phase 4 (Operational Validation) is modified as follows:

| §7.2.2 Phase 4 element | Traditional MAP | MAP-of-1 (`single-cp`) |
|---|---|---|
| 72-hour soak under projected production load | **Required** (handbook §6 Phase 4 / §9 #2) | **Waived** — a single-CP MAP has no meaningful production-scale traffic to soak, and the CP carries the operational risk directly |
| Bilateral connectivity with ≥50% of onboarded MAPs | **Required** (handbook §9 #4) | **Waived** for the ≥50% target. **Required** for any MAP / HMAP the candidate intends to exchange with at go-live, including TOTSCo as HMAP |
| Retry & delivery policy tests (§8.7) | Required | **Required — unchanged** |
| Conflict resolution & DNS tests (§8.8) | Required | **Required — unchanged** |
| Security & negative edge cases (§8.9) | Required | **Required — unchanged** |
| §8.10 V-01 (72-hour soak) | Required | **Waived** with V-02 – V-05 still required |

The Sponsor MAP records the waivers in the Phase 5 approval record. The TAG MAY require additional evidence if subsequent operational incidents suggest a single-CP MAP-of-1 has been under-tested in this respect.

### 7.4.10 Bilateral testing of additional protocols

The CSF transport is process-agnostic. A MAP-of-1 — like any other MAP — MAY use the CSF as the transport for **niche routing** or future industry protocols beyond SforB.

- **SforB** — if the MAP-of-1 supports SforB, the §8.6 SforB baseline tests are **mandatory** for Phase 3 sign-off (no relaxation for `single-cp`).
- **Niche routing / bilateral protocols** — for any protocol the candidate adds beyond what's currently in the baseline, the candidate and its bilateral counterparty MUST **buddy-test** the protocol against each other once the Sponsor MAP has signed off the CSF transport baseline. This applies equally to traditional and `single-cp` engagements.
- **Future industry protocols** — when a future protocol (for example, **OTS Porting**, or a future bilateral notification flow) is brought onto the CSF, the TAG will add a §8.x baseline test set for it (see the standalone handbook §8 "Scope and Extensibility"). Once published, a MAP that adopts that protocol — including a MAP-of-1 — MUST pass the corresponding baseline before Sponsor sign-off.

This means a MAP-of-1 supporting only SforB completes the §8 baseline once; a MAP-of-1 that subsequently adds a niche bilateral protocol completes that protocol's baseline (if published) and its bilateral tests at the point it adds the support.

### 7.4.11 Cost model — qualitative

The MAP-of-1 cost story (qualitative; specific numbers vary by candidate):

- **Most of the operating infrastructure is already running.** A CP currently subscribing to TOTSCo already operates OAuth 2.0 client integration, DNS records, TLS endpoints, retry queues, and JSON message handling. The MAP-of-1 stack reuses these.
- **DKIM signing is the principal new component.** DKIM is RFC 6376 — there are mature reference implementations in every major language (Apache James jDKIM for Java, MailKit for .NET, etc. — see standalone handbook §12 Tooling Reference). The cost is a **one-off software-integration exercise**, not a recurring infrastructure spend.
- **Directory API serving is small.** A single-CP registry is a few-kilobyte JSON document. Any web framework can serve it.
- **Sponsor fee is free by default; one-off and capped** at **£3,000 + VAT** for traditional engagements, or **£350 + VAT** for `single-cp` engagements, only when significant Sponsor MAP support is required (see §7.4.5). Charged once per MAP regardless of how many protocols it eventually carries.
- **The savings are the recurring TOTSCo charges.** The MAP-of-1's running cost is principally a small increment over what the CP was already paying for its TOTSCo integration; the operating saving is the **removal of TOTSCo subscription and per-unit fees**. A CP whose annual TOTSCo spend exceeds the one-off MAP-of-1 build plus the annual marginal cost of the additional CSF-specific components has a positive business case.

CPs SHOULD produce their own business case using their own commercial inputs. The framework provides no transport fees of its own.

### 7.4.12 What a MAP-of-1 *does not* lose

A CP moving from TOTSCo to a CSF MAP-of-1 retains:

- Its end-consumer relationship and CRM
- Its SORs and ServiceIdentities (the transport change does not propagate down)
- Its existing OAuth 2.0 / DNS / TLS infrastructure (most of it is reused)
- Its industry contact-details discoverability — the CSF Directory carries CP-to-CP, CP-to-MAP, MAP-to-MAP, and MAP-to-CP contact entries (phone, email, ticketing URL, purpose tags, availability hours). **The TOTSCo OTS CP-to-CP tool is not mandated for SforB**; the CSF registry contact entries replace the need for a specialised industry tool.
- Its right to come back — the CP can move from MAP-of-1 to a managed-MAP relationship later via the §7 normal transition process or, if necessary, §8.2 CP Emergency Migration.

## 7.5 Testing in Production

The CSF supports testing in production during onboarding:

- All test traffic MUST be explicitly marked as test in the audit record held in the JAM envelope
- The onboarding MAP MUST override the test flag until the CP has passed exit criteria — even if the CP sets it
- A published set of test data assets is available for entry criteria testing, performed locally with the MAP using a Virtual Test Host
- A hidden set of unit tests forms the exit criteria before the CP is granted production status
- PKI verification tools are available to assist with setup and testing

> **Note**: Not all CPs will have SIT/UAT environments. The CSF is designed to support continuous onboarding throughout core business hours, with strict protocols and test-flagging to prevent test traffic from affecting production operations.

## 7.6 Memorandum of Understanding (MoU)

MAPs and CPs that collaborate on the CSF are bound by a Memorandum of Understanding that outlines the terms of participation. The MoU is designed to be simple to join, reflecting the CSF's nature as an open standard that is licence-free for any CP or MAP to use for any purpose.