---
title: 6. TOTSCo Integration
tags: [Part 2]

---

# 6. TOTSCo Integration

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

## 6.1 Overview

TOTSCo operates centralised hubs for both **One Touch Switch (OTS)** residential switching and **Switching for Business (SforB)**. Both hubs use the same **JAM message envelope** specification and the same **OAuth 2.0 over TLS 1.3** transport that the CSF uses, which gives the two networks strong compatibility at the message layer. For SforB, TOTSCo can participate in the CSF as a **Hub Managed Access Provider (HMAP)** — routing messages between its connected CPs and the wider CSF network.

This chapter describes how the CSF and TOTSCo interoperate. The detailed implementation plan has been shared separately with TOTSCo and is available on request from the TAG.

> **CP migration path (SforB and non-OTS only).** A CP currently using TOTSCo for **SforB** (and / or for niche bilateral exchanges or other non-OTS protocols) who wishes to **become a MAP of 1 on the CSF** for that traffic is covered by [Part 1 §7.4 *MAP-of-1 Onboarding (incl. TOTSCo → CSF Migration)*](../part1-framework/07-onboarding.md#74-map-of-1-onboarding-incl-totsco--csf-migration). The CSF treats this as a first-class adoption path; the strong JAM-envelope compatibility makes the move a transport switch rather than a business change. **OTS is out of scope** — OTS is Ofcom-mandated to use TOTSCo as the single industry platform, so a CP that operates OTS MUST continue to use TOTSCo for OTS traffic. The migration applies to SforB and other non-OTS protocols only.

## 6.2 Integration Principles

- **Zero to low impact** on existing TOTSCo infrastructure
- The CSF uses the **same JAM message specification** and **OAuth 2.0 authentication** as TOTSCo
- No modifications to the TOTSCo letterbox API are required
- TOTSCo's existing OTS connections with MAPs can be reused

## 6.3 Registering CSF Endpoints

**Impact: Zero to Low**

It is highly probable that existing MAPs already have connectivity with TOTSCo from OTS or SforB. Any new MAP or MAP-of-1 joining the CSF must also register with TOTSCo following their existing procedures:

- Provide IP addresses for allowlisting
- Exchange OAuth 2.0 or API key credentials
- Confirm message exchange conforms to the JAM Specification

The only additional requirement is a **Directory API endpoint URL** for TOTSCo to retrieve the MAP's CSF registry.

### 6.3.1 Dedicated, locked-down HMAP interfaces — both directions

The CSF and TOTSCo deliberately adopt a **per-partner, dedicated-endpoint** operating model in both directions. This mirrors how TOTSCo already runs OTS and SforB today — every CP and MAP that connects to the TOTSCo Hub does so through an endpoint TOTSCo provisions specifically for that partner.

| Direction | What the MAP does | What TOTSCo does |
|---|---|---|
| **MAP-side (inbound to the MAP from TOTSCo)** | Each CSF MAP exposes a **dedicated HMAP interface exclusively for TOTSCo**. This interface is not used by any other MAP or HMAP. It is **locked down** at the agreed contract — CSF spec increments, feature releases, envelope changes, and routing-group additions do **not** propagate through this interface. TOTSCo's exchanges with the MAP continue to work exactly as they did on day one. | TOTSCo treats the MAP's HMAP interface as a stable bilateral contract. |
| **TOTSCo-side (inbound to TOTSCo from the MAP)** | The CSF MAP delivers SforB messages to a dedicated TOTSCo letterbox URL provisioned specifically for that MAP. | TOTSCo provisions **one dedicated CSF letterbox URL per CSF MAP**, the same per-partner pattern TOTSCo already uses for every OTS / SforB partner today. Each URL is backed by the same hub infrastructure; only the URL path differs. |

> **Why locked down.** The architectural commitment to TOTSCo is that the HMAP interface is **steady-state**. The CSF can — and will — continue to evolve at its own cadence; that evolution happens behind each MAP's standard CSF interface, not through the dedicated HMAP interface TOTSCo consumes. This keeps TOTSCo's integration a one-time build, not an evergreen one, and isolates TOTSCo's regulated OTS operations from any CSF iteration.

> **Best Practice (legacy heading retained for backward compatibility of cross-references).** All MAPs should configure a dedicated, locked-down HMAP interface for TOTSCo. This is mandatory in the operating model described above and is the only pattern this section supports.

## 6.4 Directory Collection

**Impact: Medium**

TOTSCo must collect the CP Registry from each MAP on the CSF network. This involves:

1. **Accessing each MAP's CP Registry endpoint** using existing OAuth 2.0 credentials
2. **Converging the collected CP Registries** into a Master Registry — either merged with the existing TOTSCo directory or maintained separately
3. **Updating periodically** — every 5 minutes, hourly, or daily, at TOTSCo's discretion

The CSF CP Registry is intentionally a **strict superset** of the TOTSCo directory structure for OTS and SforB, making convergence straightforward. TOTSCo can choose to retain all data, or use the CSF-specific fields (`signing[]`, expanded `resource[]`, `contact[]`, `outage[]`) for the value they add, or ignore them entirely — none of those choices break TOTSCo's existing parser.

**Dual-process directory in TOTSCo today.** TOTSCo's pre-production Directory v2 already serves both OTS and GPLB (SforB) entries from a single list, distinguishing them by `processSupport[].process`. MAPs that want a single-process view filter on an `identity` query parameter:

```
https://preprod.otshub.totsco.co.uk/directory/v2/entry?listType=RCPID&identity=all
https://preprod.otshub.totsco.co.uk/directory/v2/entry?listType=RCPID&identity=ots
https://preprod.otshub.totsco.co.uk/directory/v2/entry?listType=RCPID&identity=gplb
```

The production model is expected to follow the same shape. The CSF's Master Registry follows the same convention (`processSupport[].process` carries `OTS`, `GPLB`, and future process tags), so TOTSCo can apply its existing filter logic unchanged.

The number of CSF MAPs is anticipated not to exceed ten initially.

## 6.5 RCPID Format Handling

**Impact: Low**

The SforB Message Specification defines source and destination identity fields as strings (up to 256 characters). The CSF uses UUIDv4 (36 characters) — well within this constraint.

In practice:

- **CSF MAP sending to TOTSCo**: Uses the destination RCPID from the TOTSCo directory (typically 4-character OTS format)
- **TOTSCo sending to CSF MAP**: Uses the destination RCPID from its Master Registry (UUIDv4 format, collected from CSF CP Registries)

TOTSCo automatically acquires all CP UUIDs when collecting MAP registries. Both CSF and TOTSCo already accept UUIDv4 for correlation IDs.

## 6.6 API Compatibility

**Impact: Zero**

TOTSCo uses the industry JAM Specification for message exchange — the same standard used by the CSF. The CSF validates the JSON envelope identically and uses OAuth 2.0 over TLS 1.3.

| Aspect | TOTSCo | CSF | Compatible? |
|---|---|---|---|
| Message format | JAM Specification | JAM Specification | Yes |
| Envelope validation | Same rules | Same rules | Yes |
| Authentication | OAuth 2.0 | OAuth 2.0 | Yes |
| Transport | TLS 1.3 | TLS 1.3 | Yes |
| Success response | HTTP 202 | HTTP 202 | Yes |
| Error codes (sync) | 9xxx | 9xxx + 8xxx (PKI only) | Yes |

The 8xxx PKI error codes are CSF-specific and are not sent to TOTSCo. No API modifications are required on the TOTSCo side.

## 6.7 Message Flow: CSF to TOTSCo

In CSF, **CP 1 and MAP A are treated as a single unit at the transport layer** — the MAP handles all CSF message exchange, and the CP only gives the MAP internal instructions and receives internal nudges back when action is required. This is true whether the CP is operating as a **MAP-of-1** (CP and MAP are literally the same entity) or is a CP being served by a separate MAP. The mermaid diagram below uses a grouping box to make this visible.

```mermaid
sequenceDiagram
    box CSF — CP 1 + MAP A treated as one unit (e.g. MAP-of-1)
        participant CP1 as CP 1 (CSF)
        participant MAPA as MAP A (CSF)
    end
    participant TOTSCo as TOTSCo (HMAP)
    participant CP2 as CP 2 (TOTSCo)

    Note over CP1,MAPA: All CSF message exchange is handled by MAP A.<br/>CP 1 gives MAP A internal instructions and receives<br/>internal nudges back when action is required.
    CP1->>MAPA: Internal instruction (e.g. "perform Switch Match")
    Note over MAPA: Look up destination in directory<br/>Destination CP is on TOTSCo
    MAPA->>TOTSCo: OAuth 2.0 auth + JAM message<br/>(standard TOTSCo letterbox)
    TOTSCo-->>MAPA: HTTP 202
    TOTSCo->>CP2: Forward message to destination CP
```

## 6.8 Message Flow: TOTSCo to CSF

The same CSF grouping applies on the inbound side — MAP A receives the message from TOTSCo on behalf of CP 1, and CP 1 is notified internally if the message requires action.

```mermaid
sequenceDiagram
    participant CP2 as CP 2 (TOTSCo)
    participant TOTSCo as TOTSCo (HMAP)
    box CSF — CP 1 + MAP A treated as one unit (e.g. MAP-of-1)
        participant MAPA as MAP A (CSF)
        participant CP1 as CP 1 (CSF)
    end

    CP2->>TOTSCo: SforB message (JAM envelope)
    Note over TOTSCo: Look up destination in Master Registry<br/>Destination CP is on MAP A
    TOTSCo->>MAPA: OAuth 2.0 auth + JAM message<br/>(destination RCPID is UUIDv4)
    MAPA-->>TOTSCo: HTTP 202
    MAPA->>CP1: Internal nudge to CP (if action required)
    Note over MAPA,CP1: MAP A handles all CSF message exchange.<br/>CP 1 only receives internal nudges for actions it needs to perform.
```

## 6.9 PKI Considerations

TOTSCo, as an HMAP, is **not required** to implement DKIM/PKI signing when exchanging messages on behalf of its CPs. This is by design — to minimise integration cost for hub operators.

However:

- TOTSCo **is strongly recommended** to implement the full CSF CP Registry format for SforB, as its CP clients benefit significantly from the additional contact and support information
- TOTSCo **is not precluded** from implementing PKI if desired — the CSF framework supports it
- When a CSF MAP receives a message from TOTSCo's dedicated endpoint, it knows the message comes from a trusted hub and applies hub-specific validation rules rather than PKI verification

## 6.10 Passthrough Headers

When TOTSCo forwards a message from a CSF MAP to its own CPs, the `X-CSF-SIGNATURE` header SHOULD be left intact. This provides end-to-end trust verification — the destination CP (or its MAP) can verify the original signing even after hub forwarding.

## 6.11 Support and Diagnostics

By accessing CSF registries, TOTSCo gains direct access to MAP contact details (phone, email, URL with availability hours), enabling prompt issue resolution.

The CSF registry provides more detailed contact information than currently available through OTS, including:
- MAP and CP support hours
- Multiple contact methods with purpose tags (sales, support, technical)
- Service status URLs for real-time operational monitoring

## 6.12 Further Information

| Document | Description |
|---|---|
| [**TOTSCo HMAP Integration Guide**](../standalone/totsco-hmap-integration-guide.md) | The **TOTSCo-side build-and-commission handbook**: executive summary for middle management, six concrete deliverables (Directory API client, Master Registry convergence, RCPID translation, routing rules, dedicated CSF letterbox URL, optional PKI), five-phase plan (Discovery → Build → Test → Operational Commissioning → Production), copy-and-run test patterns, cost-and-effort estimate, risk register, and collective industry-benefit framing. Companion to this chapter; **read this guide alongside §6**. |
| TOTSCo Integration — Implementation Plan v1.1 | Detailed integration steps (shared with TOTSCo) |
| TOTSCo Integration — Overview Slides v1.0 | High-level integration overview |
| [TOTSCo Hub API Specification v2.0](https://totsco.org.uk/wp-content/uploads/2026/04/TOTSCo-API-specifications-v2-Clean.pdf) | Industry-standard letterbox and directory API specification for SforB |

These documents are available on request from the TAG.