Connect a partner endpoint

A connection is a partner OCPI endpoint you test against. Create it with the token they gave you, then register it to perform the live OCPI credentials handshake.

Choose test or production

Adding an endpoint asks Is this a test system or a live production system? There is no preselected answer. The API requires partnerEnvironment, either test or production, too. Choose test only when your partner permits test objects, commands and deliberate bad behaviour. Production sweeps send GET requests only. Withheld writes are Not tested with their reason, so passing reads give Partial coverage. Journeys, scheduled journeys and manual writes are refused. Registering, verifying, updating credentials and unregistering remain available. Existing endpoints count as test systems. Confirm that once on the endpoint card, or mark the endpoint production. The creator or an admin can use the card’s change control or PUT /connections/:id/environment. Changes are audited. Conformance runs and ordinary journeys already admitted retain their recorded environment. Queued or running load tests stop before another write when the endpoint or its hub companion is marked production.

curl -fsS -X PUT "https://chargerdojo.com/api/v1/connections/$CONNECTION_ID/environment" \
  -H "Authorization: Bearer $DOJO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partnerEnvironment":"production"}'

Objects a run invents use CONF- for a conformance sweep or JRN- for a journey. An invented EVSE ID keeps its standard format and carries CONF or JRN in its local identifier. Partner-served identifiers and registered party identities stay unchanged. Use these markers to find test data on the partner. Accepted CDRs cannot be deleted; credit them instead.

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 for this direction. 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, they mean to register into you instead, which is the opposite direction and has its own page. See OCPI 2.2.1 registration.

The address has no shape you can guess

The base URL travels out of band with Token A, and for the same reason: the spec never defines what it looks like. “The protocol is designed such that the exact URLs of the endpoints can be defined by each party”, and the example URLs in the specification “are descriptive only”. So /ocpi, /api/ocpi and /ocpi-2.2.1 are all legal bases, and only your partner knows which one is theirs. Ask them for it rather than deriving it from anything else they sent you. See OCPI 2.2.1 Versions and Transport and Format: Interface endpoints. The one that catches people is the versions URL itself. What a partner hands over is usually the full .../ocpi/versions, and this field wants the URL that hangs off, one segment shorter. Paste the whole thing and we ask for .../ocpi/versions/versions, which no server advertised. On the Endpoints page the line under the address names the exact URL the next press will ask for, so a value one segment out shows itself before it costs you a connection. If you are not sure which of the two you were given, press Check this address and we try the likely candidates and report what each one answered.

Create the connection

Operation reference: POST /connections.

curl -fsS -X POST "https://chargerdojo.com/api/v1/connections" \
  -H "Authorization: Bearer $DOJO_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",
    "partnerEnvironment": "test"
  }'

Field	Notes
`partnerBaseUrl`	Their OCPI base URL. It has to be reachable from the internet; if the endpoint you are testing runs on your own machine or inside a VPC, put a tunnel in front of it first, or run the connector, which never exposes it.
`ourRole`	`CPO` or `EMSP`. The role you are testing as. New to those two? Glossary.
`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.

Roles and request direction

The roles you select describe the businesses. Sender and Receiver describe a module’s data interface, so they do not say who starts registration.

Roles	Request direction
CPO target, ChargerDojo as eMSP	ChargerDojo pulls Locations from the CPO’s Sender interface.
eMSP target, ChargerDojo as CPO	ChargerDojo pushes a Session to the eMSP’s Receiver interface.
Partner’s client, ChargerDojo as Credentials Receiver	Their client starts the handshake; ChargerDojo calls back to their advertised URL.

Sources: OCPI 2.2.1 InterfaceRole and OCPI 2.2.1 registration. The OCPI 2.2.1 Endpoint class note says “for the credentials module, the value of the role property is not relevant as this module is the same for all roles.” The educational simulator edits hosted state and does not call your partner.

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.

Sources: OCPI 2.1.1 request format; OCPI 2.2.1 Authorization header.

Register: the live credentials handshake

Operation reference: POST /connections/{id}/register.

curl -fsS -X POST "https://chargerdojo.com/api/v1/connections/$CONNECTION_ID/register" \
  -H "Authorization: Bearer $DOJO_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

Operation reference: GET /connections, GET /connections/{id}.

curl -fsS "https://chargerdojo.com/api/v1/connections" \
  -H "Authorization: Bearer $DOJO_KEY"

curl -fsS "https://chargerdojo.com/api/v1/connections/$CONNECTION_ID" \
  -H "Authorization: Bearer $DOJO_KEY"

Connections are shared within your organisation, including its sandbox endpoints. A connection id from another organisation answers 404. The list returns up to 50 connections by default, with external endpoints before sandboxes. Use limit up to 100 and increase skip by that limit to read subsequent pages. Stop when a page contains fewer rows than the requested limit.

When their address changes

A partner who moves hosts, or an endpoint of your own behind a tunnel that hands out a new URL, does not need a new connection. Move the one you have: Operation reference: PUT /connections/{id}/address.

curl -fsS -X PUT "https://chargerdojo.com/api/v1/connections/$CONNECTION_ID/address" \
  -H "Authorization: Bearer $DOJO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "partnerBaseUrl": "https://their-new-host.example/ocpi" }'

Their platform has not changed and neither have the tokens, so nothing is re-registered. The connection keeps its id and its own reports, drops to pending while we read their versions endpoint at the new address, and returns to registered when that answers. This is ours rather than OCPI’s. The spec’s “changing endpoints” procedure is a credentials PUT that carries your versions URL, so it tells a partner that you moved. Nothing in OCPI tells a client that the server moved, because a server’s versions URL is exchanged out of band in the first place. See OCPI 2.2.1 changing endpoints.

Run a conformance suite against the registered connection.

Get started

Guides

Changelog

API reference

Connect a partner endpoint

Choose test or production

What you need from your partner

The address has no shape you can guess

Create the connection

Roles and request direction

Pick the version they actually run, not the newest one

Register: the live credentials handshake

Read your connections

When their address changes

Next