---
title: 1. Getting Started
tags: [Part 2]

---

# 1. Getting Started

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

## 1.1 Purpose

This section provides a practical checklist for MAPs implementing the CSF. Whether you are a new MAP joining the network or an existing MAP adding CSF support, this guide covers the prerequisites and steps to get operational.

## 1.2 Prerequisites

Before beginning implementation, ensure you have:

- [ ] Read [Part 1: Framework](../part1-framework/01-introduction.md) to understand the architecture and principles
- [ ] Reviewed the [JSON Asynchronous Messaging Specification (JAM)](https://www.offta.org.uk/best-practice-guide#:~:text=Switching%20for-,Business,-GPLB%20SG%20Switching) published on the OTA2 website
- [ ] Reviewed the **RCPID Standards** (in the process of being published by OTA2; no direct link available at the time of this publication — check the [OTA2 website](https://www.offta.org.uk/) for the latest)
- [ ] Reviewed the [Switching for Business Process Documents](https://www.fcs.org.uk/gaining-provider-led-business-switching/) published on the FCS website
- [ ] Reviewed the [TOTSCo Hub API Specification v2.0](https://totsco.org.uk/wp-content/uploads/2026/04/TOTSCo-API-specifications-v2-Clean.pdf) for hub interoperability requirements
- [ ] Identified a Sponsor MAP (or been assigned one via the rotation)
- [ ] Agreed terms and costs with the Sponsor MAP for the onboarding process

## 1.3 Implementation Checklist

### Infrastructure Setup

- [ ] Provision TLS 1.3-capable endpoints for:
  - Letterbox API (message sending/receiving)
  - Directory API (registry publishing)
  - OAuth 2.0 token endpoint
- [ ] Configure OAuth 2.0 authorisation server (Client Credentials flow)
- [ ] Set up PKI key management (generation, storage, rotation)
- [ ] Implement DNS management for CP `_domainkey` and `_mapkey` TXT records

### API Implementation

- [ ] Implement the **Letterbox API** — accepting JAM-formatted JSON messages via HTTP POST, returning HTTP 202 on success (see [Message API](04-message-api.md))
- [ ] Implement the **Directory API** — serving your registry as a JSON document via HTTP GET (see [Directory API](05-directory-api.md))
- [ ] Implement **OAuth 2.0 token endpoint** — issuing access tokens to authenticated MAPs (see [OAuth 2.0 Implementation](02-oauth2-implementation.md))

### Security Implementation

- [ ] Implement **DKIM message signing** for outbound messages (see [PKI & DKIM Signing](03-pki-dkim-signing.md))
- [ ] Implement **DKIM signature verification** for inbound messages
- [ ] Implement **DNS-based CP verification** — validating the `_domainkey` and `_mapkey` records
- [ ] Generate PKI key pairs for each CP (minimum RSA-2048 or Ed25519)

### Directory and Registry

- [ ] Build and publish your **MAP registry** in the specified JSON format
- [ ] Implement **registry collection** — pulling other MAPs' registries via their directory API
- [ ] Implement **directory convergence** — merging collected registries into a unified directory
- [ ] Implement **conflict resolution** — handling CPs that appear in multiple registries

### Message Processing

- [ ] Implement **message validation** — envelope structure, RCPID verification, signing validation
- [ ] Implement **retry logic** with exponential backoff for failed deliveries
- [ ] Implement **asynchronous error handling** using 9xxx (industry) and 8xxx (CSF) error codes
- [ ] Implement **message delivery failure notifications** to the originating CP/MAP

### Operations

- [ ] Set up **monitoring and alerting** for endpoint availability
- [ ] Implement **status reporting** in the registry (incident flags, planned changes)
- [ ] Establish **audit logging** for all message exchanges
- [ ] Implement **rate limiting** and denial-of-service protections

### Onboarding

- [ ] Complete **Sponsor MAP assessment** — technical, security, and compliance review
- [ ] Establish **OAuth 2.0 credentials** with the Sponsor MAP
- [ ] Pass **connectivity testing** with provisional/restricted access
- [ ] Pass **process-level testing** with test CPs
- [ ] Pass **operational validation** — delivery reliability, retry, and SLA compliance
- [ ] Pass **exit criteria** — including hidden unit tests and PKI verification
- [ ] Establish **OAuth 2.0 credentials** with all other MAPs
- [ ] Obtain **full access** approval from Sponsor MAP

### TOTSCo Integration (if applicable to the protocol e.g. SforB)

- [ ] Register CSF endpoints with TOTSCo using existing procedures
- [ ] Configure a **dedicated endpoint for TOTSCo** (separate from CSF MAP endpoint)
- [ ] Ensure TOTSCo can access your **Directory API** using existing OAuth 2.0 credentials
- [ ] Test message exchange with TOTSCo using their existing letterbox interface

> See [TOTSCo Integration](06-totsco-integration.md) for detailed integration guidance.

## 1.4 Recommended Endpoint Structure

While the CSF does not mandate specific URL patterns, the following structure is recommended:

| Endpoint | URL Pattern | Purpose |
|---|---|---|
| OAuth Token | `https://{fqdn}/oauth2/token` | Issue access tokens |
| Directory API | `https://{fqdn}/directory` | Serve MAP registry |
| Letterbox (CSF) | `https://{fqdn}/letterbox/csf/{version}/post` | Receive messages from CSF MAPs |
| Letterbox (Hub) | `https://{fqdn}/letterbox/hub/{version}/post` | Receive messages from HMAPs (e.g., TOTSCo) |
| Service Status | `https://{fqdn}/status` | Operational status page/API |

> **Best Practice**: Maintain separate letterbox endpoints for CSF MAPs and HMAPs (e.g., TOTSCo). This allows the TAG to iterate the CSF rapidly without affecting established hub exchange networks.

## 1.5 Development Resources

| Resource                      | Location                                                                                                  |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| PKI verification testing tool | [CSF Documentation Wiki](https://github.com/nowyoyo/csf-documentation/wiki/Verification-Testing-endpoint) |
| CSF test endpoints            | Available from TAG members for integration testing                                                        |
| Virtual Test Host             | Provided by MAPs for local onboarding testing                                                             |
| Sample code (Java, C#)        | See [PKI & DKIM Signing — Worked Examples](03-pki-dkim-signing.md#38-worked-examples)                        |
| OpenAPI specification         | See `letterbox-openapi.yaml` in the CSF documentation repository                                          |
| TOTSCo Basic Connectivity testing         |    https://totsco.org.uk/business-user-guide/                                     |