Skip to content

Protocol Overview

This document outlines the essential operational principles and workflows that underpin OCPI integrations. It serves as a high-level guide for platform architects and developers to ensure interoperability, security, and maintainability when implementing OCPI-compliant systems.

Discovery Workflow

  • Version negotiation — /ocpi/versions enumerates protocol releases and exposes the endpoints available per role . Providers should return every supported version, even if only one is enabled for production today, so partners can schedule upgrades ahead of time.
  • Module handshake — once both sides settle on a version, call /ocpi/{role}/{version}/modules to confirm which functional modules are online. Reject the session with status code 3003 when mandatory endpoints are missing; the spec’s table in version_information_endpoint.asciidoc lists the expected URLs.
  • First sync — the initializing party performs a GET on the counterparty’s credentials endpoint to fetch the token it will use for subsequent requests, then POSTs its own credentials object. Plan to refresh cached modules metadata whenever either party rotates tokens.
  • Transport contract — OCPI is strictly HTTPS + JSON. Authorization headers must carry a Base64 encoded credentials token; missing encoding is still common in legacy 2.1.1 installs, so add feature flags if you interoperate with them. Enforce pagination headers (Link, X-Total-Count, X-Limit) on every list endpoint and document the server-side cap your platform imposes.

Security & Lifecycle

  • Token lifecycle — credentials tokens are long-lived but must be revocable. docs/ocpi-spec/credentials.asciidoc#credentials_registration prescribes the rotate-and-confirm flow: POST a new credentials object, wait for the counterparty’s GET confirmation, then invalidate the old token. Automate this as part of your secrets management.
  • TLS expectations — the spec mandates server-side TLS only; no client certificates are required. Nevertheless, VEMO enforces modern cipher suites and rejects plaintext callbacks. Capture this in onboarding runbooks so partners provision appropriate certificates.