OCPI handshake cookbook

This cookbook is for OCPI peers — third-party CPOs and eMSPs — establishing a roaming relationship with the PixellEnergy platform under OCPI 2.2.1 §7 (Credentials and Registration). Familiarity with OCPI module semantics is assumed; the cookbook walks the PixellEnergy-specific decisions only.

You will need, before you start:

• A peer party_id (3 chars) + country_code (ISO 3166-1 alpha-2) issued by your roaming registry.
• HTTPS-reachable endpoints implementing the OCPI 2.2.1 surface for each module you intend to enable (minimum: /versions + /credentials + at least one data module).
• A bootstrap Token A issued out-of-band by PixellEnergy.
• Operations contact + DPO contact (per OCPI 2.2.1 BusinessDetails and PixellEnergy's DPDP framework).

PixellEnergy operates as BOTH a CPO and an eMSP under separate party_ids on one platform:

During the handshake response, PixellEnergy returns BOTH role entries in the roles[] array. If you only intend to roam with one of the two roles, you still receive both — the OCPI 2.2.1 spec allows you to ignore the unused role. Your own peer credentials row will list one or both of your roles depending on your business model.

Token A is the bearer the peer presents on the FIRST request to the PixellEnergy CSMS. It is issued out-of-band by PixellEnergy, via secure email to your DPO contact. Token A has a 30-day TTL after which it is invalidated even if unused.

Once you have Token A, the handshake state machine begins. The full sequence (per OCPI 2.2.1 §7 + the production reference at packages/api/src/ocpi/credentials.ts):

Peer (CPO/eMSP)                            PixellEnergy CSMS
      |                                          |
      |  (1)  Token A issued out-of-band (email/portal) ──────────►
      |                                          |
      |  (2)  GET  /ocpi/versions                |
      |       Authorization: Token <TOKEN_A>     |
      |  ────────────────────────────────────────►
      |       200 OK { versions: [2.2.1] }       |
      |  ◄────────────────────────────────────────
      |                                          |
      |  (3)  POST /ocpi/2.2.1/credentials       |
      |       Authorization: Token <TOKEN_A>     |
      |       body: { token: <YOUR_TOKEN_B>, .. }|
      |  ────────────────────────────────────────►
      |       200 OK { token_b: <PXE_TOKEN_B> }  |  (Token A invitation consumed)
      |  ◄────────────────────────────────────────
      |                                          |
      |  (4)  PUT  /ocpi/2.2.1/credentials       |
      |       Authorization: Token <PXE_TOKEN_B> |
      |       body: { token: <YOUR_TOKEN_C>, .. }|
      |  ────────────────────────────────────────►
      |       200 OK { credentials, no token }   |  (status=ACTIVE)
      |  ◄────────────────────────────────────────
      |                                          |
      |  (5+) Module calls (locations, sessions, |
      |       cdrs, tariffs, tokens, commands)   |
      |       Authorization: Token <YOUR_TOKEN_C>|
      |  ◄═════════════════════════════════════►

With Token A in hand, your first call is GET /ocpi/versions (unversioned, per OCPI 2.2.1 §4.2 — it sits above the version-prefixed modules). This is the deliberate shape of OCPI — peers exchange a list of supported versions so a future v2.3 / v3.0 upgrade is non-breaking for older peers.

curl -X GET 'https://api.pixellenergy.com/ocpi/versions' \
  -H 'Authorization: Token <TOKEN_A>' \
  -H 'X-Request-ID: req-<your-ulid>'

{
  "data": [
    {
      "version": "2.2.1",
      "url": "https://api.pixellenergy.com/ocpi/2.2.1"
    }
  ],
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2026-05-18T08:00:00Z"
}

The PixellEnergy CSMS only supports 2.2.1 today. The response links the version-details URL /ocpi/2.2.1, but that version-details document is not served yet. The modules PixellEnergy receives are credentials, commands, tokens, locations, sessions, cdrs and tariffs, all under /ocpi/2.2.1/. OCPI peer endpoints are not part of the REST API reference.

Inbound OCPI is off until PixellEnergy enables it for your onboarding: until then every peer-facing route answers 503 OCPI_INBOUND_DISABLED. Once it is on, a Token A that was not issued as a PixellEnergy invitation is refused with 403 OCPI_INVITATION_REQUIRED.

The peer presents Token A in the Authorization header and YOUR freshly-minted Token B in the body. PixellEnergy creates an ocpi_credentials row (status: PENDING) holding YOUR Token B (vaulted) plus a freshly-minted PixellEnergy Token B which it returns in the response — this is the bearer PixellEnergy expects when YOU call IT.

curl -X POST 'https://api.pixellenergy.com/ocpi/2.2.1/credentials' \
  -H 'Authorization: Token <TOKEN_A>' \
  -H 'Idempotency-Key: ocpi-handshake-<your-ulid>' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "<YOUR_TOKEN_B_FOR_INBOUND_CALLS>",
    "url": "https://your-peer.example.com/ocpi/2.2.1/versions",
    "roles": [
      {
        "role": "CPO",
        "business_details": { "name": "Your CPO Name" },
        "party_id": "ABC",
        "country_code": "IN"
      }
    ]
  }'

{
  "data": {
    "credentials": {
      "ocpi_peer_id": "<uuid>",
      "tenant_id": "<uuid>",
      "party_id": "ABC",
      "country_code": "IN",
      "role": "CPO",
      "base_url": "https://your-peer.example.com/ocpi/2.2.1/versions",
      "business_details": { "name": "Your CPO Name", "website": null, "logo": null },
      "status": "PENDING",
      "last_handshake_at": "2026-05-18T08:00:01Z",
      "created_at": "2026-05-18T08:00:01Z",
      "updated_at": "2026-05-18T08:00:01Z"
    },
    "token_b": "<TOKEN_B_FROM_PIXELLENERGY>"
  },
  "error": null
}

With BOTH parties holding the other's Token B, the peer comes back with PUT — presenting PixellEnergy's Token B in the Authorization header and YOUR Token C in the body. PixellEnergy stores YOUR Token C (in Supabase Vault, plus a SHA-256 lookup hash) and flips the peer row's status to ACTIVE.

curl -X PUT 'https://api.pixellenergy.com/ocpi/2.2.1/credentials' \
  -H 'Authorization: Token <TOKEN_B_FROM_PIXELLENERGY>' \
  -H 'Idempotency-Key: ocpi-token-c-<your-ulid>' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "<YOUR_TOKEN_C_FOR_INBOUND_CALLS>",
    "url": "https://your-peer.example.com/ocpi/2.2.1/versions",
    "roles": [
      {
        "role": "CPO",
        "business_details": { "name": "Your CPO Name" },
        "party_id": "ABC",
        "country_code": "IN"
      }
    ]
  }'

{
  "data": {
    "credentials": {
      "ocpi_peer_id": "<uuid>",
      "party_id": "ABC",
      "country_code": "IN",
      "role": "CPO",
      "status": "ACTIVE",
      "...": "same fields as the POST credentials object"
    }
  },
  "error": null
}

With Token C exchanged, both sides MAY now call any of the OCPI 2.2.1 modules. PixellEnergy ships the following at v1:

Each module call MUST present Token C as the bearer and SHOULD include an X-Request-ID header for correlation in support tickets.

OCPI is bidirectional. PixellEnergy publishes to YOUR endpoints (CPO → eMSP locations push; eMSP → CPO tokens push) and accepts inbound calls from your endpoints (eMSP → CPO commands; CPO → eMSP CDRs pull). The retry policy on PixellEnergy's outbound worker:

The OCPI 2.2.1 spec is sparse on credential rotation; PixellEnergy ships explicit super_admin admin routes (Wk 15 D4 + Wk 16 D2) that a tenant can use to revoke or rotate a peer's Token C without a full TERMINATE + new-onboarding cycle.

curl -X POST 'https://api.pixellenergy.com/v1/ocpi/peers/ABC/revoke' \
  -H 'Authorization: Bearer <your-super-admin-jwt>' \
  -H 'Idempotency-Key: ocpi-revoke-<your-ulid>' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_code": "IN",
    "reason": "Peer migrated to a new party_id; rotating per OCPI 2.2.1 §4.4.5."
  }'

curl -X POST 'https://api.pixellenergy.com/v1/ocpi/peers/ABC/credentials/rotate' \
  -H 'Authorization: Bearer <your-super-admin-jwt>' \
  -H 'Idempotency-Key: ocpi-rotate-<your-ulid>' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_code": "IN"
  }'

Monthly OCPI settlement statements roll up the prior month's roaming CDRs into one net-settlement statement per peer. PixellEnergy's settlement generator produces them on the 1st of each month at 04:00 IST. Each statement is sealed (immutable) and carries a per-CDR CSV + JSON artefact and an audit-chain anchor hash. PixellEnergy operators read them via GET /v1/settlement-statements and GET /v1/settlement-statements/{statement_id}.

There is no peer-facing endpoint for statements or disputes. Ask your PixellEnergy contact for the statement, and raise any dispute with them, citing the statement and the disputed CDR ids.

• Reconcile your CDR ledger against PixellEnergy's settlement statement within 5 business days of receipt.
• India-domestic peers MUST honour Mumbai-only data residency and 30-day DSR resolution per DPDP.
• Honour the OCPI 2.2.1 X-Request-ID dedup key on EVERY mutating call (PUT/POST).
• For OCPI peers operating as a CPO under PixellEnergy's eMSP badge: enforce SignedMeterValue on OCPP 2.0.1 sessions — required for IRN issuance.
• Rotate Token C every 12 months minimum. PixellEnergy will issue a deprecation notice 30 days before forced rotation if a token exceeds the limit.
• Outage notification: any peer planning ≥ 30 minutes of unavailability for the OCPI inbound surface MUST notify ocpi-ops@pixellenergy.com 24h in advance — avoids spurious DLQ accumulation.

For onboarding queries, write to ocpi-onboarding@pixellenergy.com; for production incidents, the same address routes to the on-call rotation. Cross-link the OCPP onboarding cookbook if your peer also owns physical chargers connecting to the PixellEnergy gateway.