> ## Documentation Index
> Fetch the complete documentation index at: https://dynamo-csms.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Dynamo CSMS to Roaming Networks via OCPI

> Register Dynamo CSMS as a CPO with an eMSP roaming partner using OCPI 2.2.1, then expose locations, sessions, CDRs, tariffs, and token management.

OCPI (Open Charge Point Interface) is an open protocol that lets EV charging networks interoperate. By connecting Dynamo CSMS to an eMSP (e-Mobility Service Provider) via OCPI, drivers who subscribe to that eMSP can authenticate and charge at your stations — even without a Dynamo account.

Dynamo CSMS acts as the **CPO (Charge Point Operator)** role in OCPI exchanges. This guide shows you how to register with an eMSP roaming partner and use the key data endpoints.

<Note>
  Dynamo CSMS supports OCPI 2.2.1. If your roaming partner only supports 2.1.1, contact Dynamo support to discuss compatibility options before proceeding.
</Note>

## How OCPI registration works

OCPI uses a credentials handshake to establish a trusted connection between two parties. The sequence is:

1. Fetch the list of supported OCPI versions from your partner.
2. Retrieve the version detail to discover module URLs.
3. Exchange credentials tokens — your partner sends you a `TOKEN_A`, and after registration you receive a permanent `TOKEN_C`.
4. Use `TOKEN_C` in all subsequent OCPI requests.

<Steps>
  <Step title="Discover OCPI versions">
    Check which OCPI versions Dynamo supports.

    ```bash theme={null}
    curl -X GET https://api.dynamo-csms.com/ocpi/versions \
      -H "Authorization: Token TOKEN_A_FROM_YOUR_EMSP_PARTNER"
    ```

    Response:

    ```json theme={null}
    {
      "data": [
        {
          "version": "2.2.1",
          "url": "https://api.dynamo-csms.com/ocpi/versions/2.2.1"
        }
      ],
      "status_code": 1000,
      "status_message": "Success",
      "timestamp": "2026-05-01T13:00:00Z"
    }
    ```
  </Step>

  <Step title="Get version detail">
    Retrieve module endpoint URLs for OCPI 2.2.1.

    ```bash theme={null}
    curl -X GET https://api.dynamo-csms.com/ocpi/versions/2.2.1 \
      -H "Authorization: Token TOKEN_A_FROM_YOUR_EMSP_PARTNER"
    ```

    Response:

    ```json theme={null}
    {
      "data": {
        "version": "2.2.1",
        "endpoints": [
          { "identifier": "credentials", "role": "CPO", "url": "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/credentials" },
          { "identifier": "locations",   "role": "CPO", "url": "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/locations" },
          { "identifier": "sessions",    "role": "CPO", "url": "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/sessions" },
          { "identifier": "cdrs",        "role": "CPO", "url": "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/cdrs" },
          { "identifier": "tariffs",     "role": "CPO", "url": "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/tariffs" },
          { "identifier": "tokens",      "role": "CPO", "url": "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/tokens" },
          { "identifier": "commands",    "role": "CPO", "url": "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/commands" }
        ]
      },
      "status_code": 1000,
      "status_message": "Success",
      "timestamp": "2026-05-01T13:00:05Z"
    }
    ```
  </Step>

  <Step title="Register credentials with the eMSP">
    Send your CPO credentials to your roaming partner. Include the token you want them to use for future requests to Dynamo (`TOKEN_C`), along with your business details and your own OCPI versions URL.

    ```bash theme={null}
    curl -X POST https://api.dynamo-csms.com/ocpi/cpo/2.2.1/credentials \
      -H "Authorization: Token TOKEN_A_FROM_YOUR_EMSP_PARTNER" \
      -H "Content-Type: application/json" \
      -d '{
        "token": "TOKEN_C_YOU_GENERATE_FOR_EMSP",
        "url": "https://api.dynamo-csms.com/ocpi/versions",
        "roles": [
          {
            "role": "CPO",
            "business_details": {
              "name": "Dynamo CSMS",
              "website": "https://dynamo-csms.com",
              "logo": {
                "url": "https://dynamo-csms.com/logo.png",
                "category": "OPERATOR",
                "type": "png",
                "width": 512,
                "height": 512
              }
            },
            "party_id": "DYN",
            "country_code": "GB"
          }
        ]
      }'
    ```

    Response:

    ```json theme={null}
    {
      "data": {
        "token": "TOKEN_C_RETURNED_BY_EMSP",
        "url": "https://emsp-partner.example.com/ocpi/versions",
        "roles": [
          {
            "role": "EMSP",
            "party_id": "EMP",
            "country_code": "NL",
            "business_details": {
              "name": "Example eMSP NL"
            }
          }
        ]
      },
      "status_code": 1000,
      "status_message": "Success",
      "timestamp": "2026-05-01T13:01:00Z"
    }
    ```

    Store `TOKEN_C_RETURNED_BY_EMSP` — use it in the `Authorization: Token` header for all subsequent requests to this eMSP partner's OCPI endpoints.
  </Step>

  <Step title="Verify your registration">
    Confirm the handshake succeeded by fetching your own credentials back.

    ```bash theme={null}
    curl -X GET https://api.dynamo-csms.com/ocpi/cpo/2.2.1/credentials \
      -H "Authorization: Token TOKEN_C_YOU_GENERATE_FOR_EMSP"
    ```

    A `status_code` of `1000` confirms successful registration.
  </Step>
</Steps>

## Locations

Expose your charging locations to the roaming partner so their drivers can discover and navigate to your chargers.

```bash theme={null}
curl -X GET "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/locations?limit=10&offset=0" \
  -H "Authorization: Token TOKEN_C_YOU_GENERATE_FOR_EMSP"
```

Response:

```json theme={null}
{
  "data": [
    {
      "country_code": "GB",
      "party_id": "DYN",
      "id": "LOC001",
      "name": "Riverside Business Park",
      "address": "12 Riverside Way",
      "city": "Bristol",
      "postal_code": "BS1 4AA",
      "country": "GBR",
      "coordinates": {
        "latitude": "51.454500",
        "longitude": "-2.587900"
      },
      "evses": [
        {
          "uid": "EVSE001",
          "evse_id": "GB*DYN*E001*1",
          "status": "AVAILABLE",
          "connectors": [
            {
              "id": "1",
              "standard": "IEC_62196_T2",
              "format": "SOCKET",
              "power_type": "AC_3_PHASE",
              "max_voltage": 230,
              "max_amperage": 32,
              "max_electric_power": 22000
            }
          ]
        }
      ],
      "last_updated": "2026-05-01T09:00:00Z"
    }
  ],
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2026-05-01T13:05:00Z"
}
```

## Sessions

Retrieve active and completed sessions that originated via OCPI (i.e. from roaming drivers).

```bash theme={null}
curl -X GET "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/sessions?date_from=2026-05-01T00:00:00Z&limit=25" \
  -H "Authorization: Token TOKEN_C_YOU_GENERATE_FOR_EMSP"
```

Response:

```json theme={null}
{
  "data": [
    {
      "country_code": "GB",
      "party_id": "DYN",
      "id": "ses_OCPI_01HX1234",
      "start_date_time": "2026-05-01T08:12:00Z",
      "end_date_time": "2026-05-01T09:04:00Z",
      "kwh": 14.7,
      "cdr_token": {
        "uid": "RFID_TOKEN_ABC123",
        "type": "RFID",
        "contract_id": "NLEMPCONTRACT001"
      },
      "auth_method": "WHITELIST",
      "location_id": "LOC001",
      "evse_uid": "EVSE001",
      "connector_id": "1",
      "currency": "GBP",
      "status": "COMPLETED",
      "last_updated": "2026-05-01T09:04:30Z"
    }
  ],
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2026-05-01T13:06:00Z"
}
```

## Charge Detail Records (CDRs)

CDRs are the billing records generated at the end of each completed session. The eMSP uses these to invoice their drivers.

```bash theme={null}
curl -X GET "https://api.dynamo-csms.com/ocpi/cpo/2.2.1/cdrs?date_from=2026-05-01T00:00:00Z&limit=25" \
  -H "Authorization: Token TOKEN_C_YOU_GENERATE_FOR_EMSP"
```

Response:

```json theme={null}
{
  "data": [
    {
      "country_code": "GB",
      "party_id": "DYN",
      "id": "CDR_01HX5678",
      "start_date_time": "2026-05-01T08:12:00Z",
      "end_date_time": "2026-05-01T09:04:00Z",
      "session_id": "ses_OCPI_01HX1234",
      "cdr_token": {
        "uid": "RFID_TOKEN_ABC123",
        "type": "RFID",
        "contract_id": "NLEMPCONTRACT001"
      },
      "auth_method": "WHITELIST",
      "cdr_location": {
        "id": "LOC001",
        "name": "Riverside Business Park",
        "evse_uid": "EVSE001",
        "evse_id": "GB*DYN*E001*1",
        "connector_id": "1"
      },
      "currency": "GBP",
      "tariffs": [
        { "id": "TAR001", "currency": "GBP" }
      ],
      "charging_periods": [
        {
          "start_date_time": "2026-05-01T08:12:00Z",
          "dimensions": [
            { "type": "ENERGY", "volume": 14.7 }
          ]
        }
      ],
      "total_energy": 14.7,
      "total_cost": { "excl_vat": 6.17, "incl_vat": 7.40 },
      "last_updated": "2026-05-01T09:05:00Z"
    }
  ],
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2026-05-01T13:07:00Z"
}
```

## Tariffs

Publish your tariff information via OCPI so the eMSP can display pricing to drivers before they start charging.

```bash theme={null}
curl -X GET https://api.dynamo-csms.com/ocpi/cpo/2.2.1/tariffs \
  -H "Authorization: Token TOKEN_C_YOU_GENERATE_FOR_EMSP"
```

Response:

```json theme={null}
{
  "data": [
    {
      "country_code": "GB",
      "party_id": "DYN",
      "id": "TAR001",
      "currency": "GBP",
      "elements": [
        {
          "price_components": [
            { "type": "ENERGY", "price": 0.42, "vat": 20.0, "step_size": 1 },
            { "type": "FLAT",   "price": 0.50, "vat": 20.0, "step_size": 1 }
          ]
        }
      ],
      "last_updated": "2026-05-01T10:00:00Z"
    }
  ],
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2026-05-01T13:08:00Z"
}
```

## Token management

Dynamo CSMS stores driver tokens (RFID cards, app tokens) shared by the eMSP. The eMSP pushes tokens to you so you can authorise drivers offline.

<CodeGroup>
  ```bash Get a token theme={null}
  curl -X GET https://api.dynamo-csms.com/ocpi/cpo/2.2.1/tokens/NL/EMP/RFID_TOKEN_ABC123 \
    -H "Authorization: Token TOKEN_C_YOU_GENERATE_FOR_EMSP"
  ```

  ```bash Create or replace a token theme={null}
  curl -X PUT https://api.dynamo-csms.com/ocpi/cpo/2.2.1/tokens/NL/EMP/RFID_TOKEN_ABC123 \
    -H "Authorization: Token TOKEN_C_YOU_GENERATE_FOR_EMSP" \
    -H "Content-Type: application/json" \
    -d '{
      "uid": "RFID_TOKEN_ABC123",
      "type": "RFID",
      "contract_id": "NLEMPCONTRACT001",
      "issuer": "Example eMSP NL",
      "valid": true,
      "whitelist": "ALWAYS",
      "last_updated": "2026-05-01T12:00:00Z"
    }'
  ```

  ```bash Partially update a token theme={null}
  curl -X PATCH https://api.dynamo-csms.com/ocpi/cpo/2.2.1/tokens/NL/EMP/RFID_TOKEN_ABC123 \
    -H "Authorization: Token TOKEN_C_YOU_GENERATE_FOR_EMSP" \
    -H "Content-Type: application/json" \
    -d '{"valid": false, "last_updated": "2026-05-01T14:00:00Z"}'
  ```
</CodeGroup>

## Deregister from a roaming partner

To terminate the OCPI connection with a partner, delete your credentials. This revokes the exchange tokens on both sides.

```bash theme={null}
curl -X DELETE https://api.dynamo-csms.com/ocpi/cpo/2.2.1/credentials \
  -H "Authorization: Token TOKEN_C_YOU_GENERATE_FOR_EMSP"
```

Response:

```json theme={null}
{
  "status_code": 1000,
  "status_message": "Credentials deleted successfully",
  "timestamp": "2026-05-01T15:00:00Z"
}
```

<Warning>
  Deleting credentials immediately invalidates the exchange tokens. Any roaming sessions in progress will continue until they end naturally, but no new sessions from that eMSP's drivers will be authorised.
</Warning>