Connect a partner endpoint

A connection is a partner OCPI endpoint you test against. Setting one up is two API calls: create it, then register it. Creation records who you are, who they are, and the token they gave you. Registration performs the live OCPI credentials handshake, and it is the step that usually goes wrong.

What you need from your partner

Two things, and they come from them, not from us:

You need	What it is
Their OCPI base URL	The URL their versions endpoint hangs off.
Token A	A registration token they issue to you, out of band.

Token A is not something you generate. The OCPI specification is explicit that it is created by the receiving party and passed to you “in a secure way that is outside the scope of this protocol”: an email, a portal, a phone call. If your partner asks you for Token A, one of you has the roles the wrong way round, and it is worth settling that before you write any code.

Create the connection

curl -fsS -X POST "https://evsim.synergyboat.com/api/v1/connections" \
  -H "Authorization: Bearer $EVRT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerBaseUrl": "https://partner.example.com/ocpi",
    "ourRole": "EMSP",
    "theirRole": "CPO",
    "tokenA": "THEIR-TOKEN-A",
    "ocpiVersion": "2.2.1"
  }'

Field	Notes
`partnerBaseUrl`	Their OCPI base URL.
`ourRole`	`CPO` or `EMSP`. The role you are testing as.
`theirRole`	`CPO` or `EMSP`.
`tokenA`	The registration token they issued you.
`ocpiVersion`	`2.1.1`, `2.2`, `2.2.1` or `2.3.0`. Defaults to `2.2.1`.

You get back 201 with the connection, its _id, and status: "pending". Token fields are never returned, by us or in any report.

Pick the version they actually run, not the newest one

The most common setup mistake is selecting 2.2.1 because it sounds current when the partner is on 2.1.1. Every subsequent failure will then be a version mismatch wearing the costume of a protocol bug. If you do not know what they run, ask, or read their versions endpoint. OCPI 2.1.1 is still in wide production use, and there is no shame in it.

The credentials token is transported differently across versions. OCPI 2.1.1 sends it raw; from 2.2 onwards it is Base64 encoded. Get the version wrong and authentication fails on the very first request, with an error that looks nothing like a version problem. The tester handles the encoding for you, but only if you told it the right version.

Register: the live credentials handshake

curl -fsS -X POST "https://evsim.synergyboat.com/api/v1/connections/$CONNECTION_ID/register" \
  -H "Authorization: Bearer $EVRT_KEY"

This runs the real OCPI credentials handshake against the partner. It is not a simulation and not an assertion against a stored token: the tester reads their versions endpoint with Token A, posts its own credentials, and receives the token it will use for every subsequent call. On success the connection’s status becomes registered. On failure it records lastError, and that error is the thing worth reading. Registration is where OCPI integrations get stuck, and the failures follow a pattern: a side keeps presenting the dead registration token after the exchange, a partner never fetches your endpoints, or the token encoding does not match the version. The troubleshooting page walks each one.

Read your connections

curl -fsS "https://evsim.synergyboat.com/api/v1/connections" \
  -H "Authorization: Bearer $EVRT_KEY"

curl -fsS "https://evsim.synergyboat.com/api/v1/connections/$CONNECTION_ID" \
  -H "Authorization: Bearer $EVRT_KEY"

Connections are owner scoped: you see your own, plus the built-in sandbox targets. A connection id that belongs to someone else answers 404.

Run a conformance suite against the registered connection.

Get started

Guides

API reference

What you need from your partner

Create the connection

Pick the version they actually run, not the newest one

Register: the live credentials handshake

Read your connections

Next

​What you need from your partner

​Create the connection

​Pick the version they actually run, not the newest one

​Register: the live credentials handshake

​Read your connections

​Next

What you need from your partner

Create the connection

Pick the version they actually run, not the newest one

Register: the live credentials handshake

Read your connections

Next