> For the complete documentation index, see [llms.txt](https://docs.enapi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enapi.com/getting-started/set-up-your-ocpi-handshake-with-enapi.md).

# 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**.

{% hint style="info" %}
Staging (`roaming.staging.enapi.com`) uses the same OCPI implementation as production (`roaming.enapi.com`) — if it works in staging, it works live.
{% endhint %}

### 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.

{% hint style="info" %}
These settings are tested in staging during onboarding — anything that needs adjusting gets caught there.
{% endhint %}

#### 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.<br>

* **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](/getting-started/roles-and-parties-on-enapi.md) 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

* [The ENAPI Portal](/getting-started/the-enapi-portal.md)
* [Testing Your OCPI Integration](/getting-started/testing-your-ocpi-handshake-with-enapi.md)
* [Roaming](/roaming.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.enapi.com/getting-started/set-up-your-ocpi-handshake-with-enapi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.