For the complete documentation index, see llms.txt. This page is also available as Markdown.

Set up your OCPI Handshake with ENAPI

Set up your OCPI Handshake with ENAPI

An OCPI handshake is the one-time setup that exchanges credentials between your platform and ENAPI. Run it from the portal under Settings → Roaming Settings → New Handshake — a guided 4-step wizard: Handshake method → Configure connection → Connection details → Perform handshake.

Staging (roaming.staging.enapi.com) uses the same OCPI implementation as production (roaming.enapi.com) — if it works in staging, it works live.

Step 1 — Handshake method

Choose who makes the first call. Both produce the same credential pair.

  • ENAPI initiates — you provide ENAPI with your Versions URL and Token A; ENAPI initiates.

  • You initiate — ENAPI provides its Versions URL and Token A; your platform initiates.

Step 2 — Configure connection

These settings are the same regardless of method. Set a Label (optional, to tell multiple connections apart) and pick the OCPI version (e.g. 2.2.1), then answer the behaviour questions below.

These settings are tested in staging during onboarding — anything that needs adjusting gets caught there.

Base64-encoded tokens (2.2.1+)

OCPI 2.2.1 introduced Base64 encoding for the token in the Authorization header. The token in the credentials body is unchanged either way; only the header representation differs.

  • Off — raw token in the Authorization header, both directions.

  • On — Base64-encoded token in the header, both directions.

Match what your platform does.

Only DE*ENA in URL path parameters?

ENAPI forwards each request under the sender's party. If we receive an update from ES*CPO, by default the path is locations/receiver/ES/CPO.

  • Off — path uses the original sender's party (ES/CPO). Most partners want this.

  • On — path always uses ENAPI's party (DE/ENA). Use only if your platform rejects paths that don't match the handshake counterparty.

HUB topology (2.2.1+)

ENAPI operates as a HUB, sharing the HUB role plus both CPO and EMSP endpoint sets (SENDER + RECEIVER) during credentials exchange. Pick what your platform accepts:

  • Full support — accepts the HUB role and multiple endpoints per module. ENAPI presents as HUB.

  • Partial support — accepts multiple endpoints per module but not the HUB role. ENAPI sends CPO + EMSP.

  • Not supported (EMSP) — expects a single CPO counterparty, one endpoint per module.

  • Not supported (CPO) — same, mirrored: a single EMSP counterparty, one endpoint per module.

Your role — how ENAPI knows what kind of party you are

Your party type on ENAPI is taken from the role you declare in the Credentials module during the handshake. There's nothing separate to configure: whatever roles your platform sends — CPO, EMSP, NSP, NAP, PTP — is what you appear as on the platform, what counterparties see in the roaming directory, and what determines the modules you exchange.

  • Declare every role you operate. OCPI 2.2.1 and later let a party send multiple roles in one credentials exchange. If you're both a CPO and an eMSP, send both and run one connection.

  • Your role comes from the credentials, not from a setting. There's nothing to switch in the Portal. If you declared the wrong role, or your business changes, send the correct roles and refresh the handshake — the new credentials replace what ENAPI has on record.

⚠️ Check the role your platform actually sends.

  • On OCPI 2.1.1 there's nothing to check — the Credentials object has no roles array, it predates the concept. Any non-CPO party connecting on 2.1.1 is registered as an eMSP.

  • On 2.2.1 and later the roles array exists, but many platforms fill it with EMSP regardless of what they operate. We regularly receive credentials from data aggregators and payment terminal providers declaring themselves as eMSPs — often because their platform hardcodes it. If that's you, you'll appear as an eMSP to every counterparty until it's corrected.

  • What to do: if you're a data aggregator or a PTP, connect on 2.2.1 or later and check that your platform actually sends NSP / NAP or PTP. If it has already sent the wrong role, send the right one and refresh the handshake. PTPs should prefer 2.3.0, where the Payments module is fully standardised.

See Roles and Parties on ENAPI for what each role sends and receives.

OCPI-to-* routing headers

Only relevant if you host multiple parties behind one endpoint. For example, you are an eMSP with multiple parties under a single handshake and you require that each EVSE update is sent to each party separately.

  • Off — one request, no routing headers; you route internally (from path or token).

  • On — ENAPI adds OCPI-to-party-id and OCPI-to-country-code, and fans out one request per target party.

Step 3 — Connection details

This step depends on the method picked in step 1.

ENAPI initiates: Provide the details ENAPI needs to call you:

  • Versions URL — where your platform exposes its OCPI versions (e.g. https://example.com/ocpi/versions).

  • Token A (plain text) — a token you generate; ENAPI uses it once to initiate.

Click Fetch versions to continue.

You initiate: Use the values ENAPI displays to initiate from your side:

  • ENAPI ID — DE*ENA

  • Token A (and Encoded Token A, if your platform expects Base64)

  • Versions URL — e.g. https://roaming.staging.enapi.com/ocpi/versions

Register ENAPI as a counterparty in your CPMS with these values and trigger the handshake (usually a "register"/"connect" action).

Step 4 — Perform handshake

ENAPI completes the credentials exchange server-to-server: negotiates the highest mutually supported version, retrieves module endpoints, and swaps the pre-shared Token A for a permanent credential. When it's done, the handshake shows Active in Roaming Settings.

Next steps

Last updated

Was this helpful?