OCPI handshake failures
Diagnose OCPI versions and credentials exchange failures between GridOS and an eMSP or hub.
Use this guide when the OCPI credentials handshake fails or partners cannot call modules after exchange. Healthy path: OCPI credentials handshake.
Handshake checklist
- Versions — both parties expose a
versionsendpoint and share at least one common version (2.1.1 and/or 2.2.1). - Base URLs — HTTPS, correct path prefix, reachable from the partner network.
- Tokens — inbound token you issue and outbound token the partner issued are stored and sent on subsequent calls.
- Roles — CPO vs eMSP (and dual roles) match what each side registered.
- Routing headers (2.2.1) —
OCPI-from-*/OCPI-to-*headers match party ids when required.
Common failure modes
| Observation | Likely cause | What to try |
|---|---|---|
| Versions GET fails (DNS/TLS/401) | Wrong URL or mutual TLS/auth expectation | Verify versions URL in a browser or curl; confirm TLS and IP allowlists |
| No mutual version | One side only supports 2.1.1 or only 2.2.1 | Agree on a version; enable both on GridOS if the partner needs dual |
| POST credentials 4xx | Payload shape, missing endpoints list, or invalid token | Compare with versioned Credentials module pages; resend with full endpoint inventory |
| Handshake OK, Locations pull empty/403 | Token stored wrong direction or role mismatch | Re-read stored tokens; confirm CPO/eMSP module URLs |
| Push rejected | Partner versions detail stale after rotate | Re-run credentials exchange after endpoint or token changes |
| Hub path fails only on 2.2.1 | Missing HubClientInfo or routing headers | See Hub client info (2.2.1) |
Versioned references
| Version | Credentials | Introduction |
|---|---|---|
| 2.1.1 | Credentials | Introduction |
| 2.2.1 | Credentials | Introduction |
OpenAPI surfaces for integrators:
Dashboard
Use the Dashboard roaming / partner surfaces to inspect last handshake error, stored tokens (never share full secrets in tickets), and selected OCPI version. Rotate credentials only when both parties can complete a new exchange in the same change window.
Still stuck
Collect: partner role, OCPI version, versions URL (no tokens), HTTP status + OCPI status message from the failing call, and whether the failure is versions GET, credentials POST, or a later module call.