Roaming & OCPI

OCPI Tokens in Practice: How an eMSP Credential Starts a Session on Another Network

By YoHub11 min read

OCPI token roaming: EV chargers with a phone and RFID card, light lines linking stations across networks

đź’ˇ OCPI Tokens in Practice: Key Highlights

  • The eMSP owns every token. CPOs hold a cached copy.
  • The whitelist field (four values, ALWAYS to NEVER) decides what happens when the eMSP is unreachable.
  • START_SESSION carries a token the eMSP has already authorised, so the CPO must not re-check it.
  • The token’s country_code, party_id and contract_id travel into the Session and the CDR. That is how a session finds who pays.
  • Through a hub, one push reaches every CPO: one request instead of 70+ per token change on YoHub.

An OCPI token is how a driver’s credential from one network gets recognised on another. The driver taps an RFID card or presses start in an app. The charger belongs to a charge point operator (CPO) the driver has no contract with, yet the session starts, and a few days later the right e-mobility service provider (eMSP) receives the right charge detail record (CDR). What happens in between is the subject of this post.

This post is for eMSP and app engineering leads and CPO backend teams who are implementing or debugging OCPI 2.2.1. Every field and value below follows the OCPI 2.2.1 Tokens module.

What an OCPI token carries, and who owns it

In OCPI the eMSP is the data owner of the Tokens module. It issues the credential, decides whether it is valid and pays for the sessions started with it. The CPO keeps a cache so a charger can approve a known token quickly and so it knows where to send the CDR. The fields that matter:

FieldWhat it does in practice
country_code + party_idIdentify the eMSP that owns the token (2 and 3 characters).
uidWhat the charger sees: the RFID chip’s ID as read by the reader, or an ID the eMSP generates for app users. Up to 36 characters.
typeRFID, APP_USER, AD_HOC_USER or OTHER. uid and type together must be unique within the eMSP.
contract_idThe driver’s contract at the eMSP, recommended to follow the eMA ID format.
validWhether the token is usable. Tokens are never deleted; they are invalidated.
whitelistWhether the CPO may approve the token from its cache or must ask the eMSP every time.
group_idLinks tokens that act as one, such as a card and a key fob, so a session started with one can be stopped with the other.

Operationally important fields of the OCPI 2.2.1 Token object. Optional fields such as visual_number, language and energy_contract are omitted.

Keep uid and contract_id apart: the first is what the charger reads, the second is who gets billed. A CPO authorises on one and reports both.

The types behave differently: RFID cards can be approved offline, APP_USER tokens identify one app user across sessions, and AD_HOC_USER tokens are one-time IDs that bind a single session to a customer.

How a token reaches the CPO: push, pull and hub

A CPO can only approve a cached token if it has received it. OCPI gives three routes:

  • Push (normal operation). The eMSP calls PUT on the CPO’s Tokens endpoint, at /{country_code}/{party_id}/{token_uid}, when it creates a token, and PUT or PATCH when it changes one. Blocking a card is a PATCH with valid: false; there is no DELETE.
  • Pull (start-up and resync). The CPO calls GET on the eMSP’s Tokens endpoint, paginated and filtered with date_from and date_to. It is for getting in sync, never for each authorisation.
  • Check. An eMSP unsure what the CPO holds can GET a single token from the CPO.

Through a hub the same flows apply with less repetition. OCPI 2.2.1 defines a Broadcast Push: the eMSP sends one request addressed to the hub, and the hub forwards it to every connected party that implements the module. The spec names Tokens as a typical use (OCPI 2.2.1, Transport and format). In the other direction, a CPO can run one paginated GET against the hub and receive tokens from several eMSPs, each identified by its own country_code and party_id.

YoHub connects 70+ CPO networks and 40+ eMSPs as of October 2026. An eMSP linked directly to 70 CPOs makes 70 calls every time it blocks a card; through the hub it makes one (Derived from the stated party counts). The connection maths behind that is in our post on OCPI bilateral connections versus a hub.

Whitelist types: what the CPO may decide on its own

The whitelist field is the most consequential setting on a token. It tells the CPO when it may decide on its own and when it must ask the eMSP. It matters most when a charger or a link is offline:

ValueRule for the CPOWhen the eMSP is unreachable
ALWAYSApprove from the cache. Real-time authorisation is not allowed.Charging works. The eMSP does not need to build the authorize endpoint for these tokens.
ALLOWEDThe CPO chooses: cache or real-time.Charging works from the cache.
ALLOWED_OFFLINEUse real-time authorisation normally.If no answer comes back, the CPO must allow the token.
NEVERAlways ask the eMSP. No caching.Charging is refused. Right for app and ad hoc tokens; risky for RFID cards.

OCPI 2.2.1 WhitelistType values and what each means for an offline charger or eMSP outage.

One rule catches teams out. The whitelist type outranks the cached valid flag. If a token is marked valid: false but its whitelist requires real-time authorisation, the CPO must still ask the eMSP, because the token’s state might have changed since the last push.

For eMSPs it is a trade-off: ALWAYS gives the fastest tap-and-charge, but a blocked card keeps working until the PATCH lands; NEVER gives full control but ties every start to the eMSP’s uptime. The spec recommends NEVER for app and ad hoc tokens.

Real-time authorisation with POST authorize

When a token is not cached, or its whitelist asks for an online check, the CPO calls POST {tokens_endpoint}/{token_uid}/authorize on the eMSP, with an optional ?type= parameter. The request body can carry a LocationReferences object: the location_id and, optionally, the EVSE UIDs where the driver wants to charge.

The eMSP answers with an AuthorizationInfo object. Its allowed field takes one of five values: ALLOWED, BLOCKED, EXPIRED, NO_CREDIT or NOT_ALLOWED, the last meaning the token is valid but not at this location. It can also return the EVSEs the driver may use and an optional authorization_reference of up to 36 characters. When it does, the CPO must copy that reference into the Session and the CDR, which gives the eMSP a reliable key to match the bill to its own approval.

Two status codes to handle. An unknown token returns OCPI status 2004 (Unknown Token) with no data. A request without enough information to decide, such as a location-restricted token with no LocationReferences, returns 2002 (Not enough information). Treat them differently: 2004 usually means a sync gap, 2002 a request the CPO can retry with more detail.

Two constraints apply: the eMSP must keep response time minimal, since the driver is waiting at the charger, and must not refuse a token over opening hours or EVSE status, because its copy of that data may be stale.

App-started sessions: START_SESSION and STOP_SESSION

App starts use the OCPI 2.2.1 Commands module, which is asynchronous because many chargers sit on slow wireless links:

  1. The eMSP sends POST /commands/START_SESSION to the CPO with the full Token object, the location_id, an optional evse_uid and connector_id, a response_url and, if it has one, an authorization_reference.
  2. The CPO replies at once with a CommandResponse: ACCEPTED, REJECTED, NOT_SUPPORTED or UNKNOWN_SESSION, plus a timeout in seconds. It only means the CPO could pass the command on; if no result arrives within the timeout, the eMSP can assume it never will.
  3. The CPO sends the command to the charger, usually over OCPP, then posts a CommandResult to the response_url: for example ACCEPTED, EVSE_OCCUPIED, EVSE_INOPERATIVE, FAILED or TIMEOUT.

The token in a START_SESSION is already authorised by the eMSP, so the CPO must not check it again before passing it to the charger. If the charger does an OCPP authorise anyway, the CPO must not send a real-time authorisation for APP_USER or AD_HOC_USER tokens. For an RFID token it must not do so within 15 minutes of receiving the command. Re-validating app tokens is a classic cause of app starts that fail on one network only.

STOP_SESSION carries only the session_id and a response_url. A CPO returns REJECTED when the session does not belong to a customer of the eMSP asking, so the eMSP needs the CPO’s session ID from the Sessions module before it can stop anything. Through a hub, both commands are routed to the right CPO using the OCPI-to-party-id and OCPI-to-country-code headers.

From OCPI token to Session and CDR

Once a session starts, the token becomes a billing question. Both the Session object and the CDR object carry three token-related fields:

  • cdr_token: the token’s country_code, party_id, uid, type and contract_id. This is how a CDR finds the eMSP that owes for it, and the contract that eMSP will bill.
  • auth_method: AUTH_REQUEST (real-time), COMMAND (app start or reservation) or WHITELIST (cache, no call made). If it changes during a session, the CDR records the last one.
  • authorization_reference: the eMSP’s own reference, returned in the authorize response or sent with the command.

A CDR whose party_id matches no connected eMSP has nowhere to go; one with the wrong contract_id arrives but cannot be billed. Both become disputes. Our guide to CDR reconciliation covers how those mismatches are found and fixed.

What happens next depends on the market, and the two models are kept apart. In India, YoHub settles: it invoices the eMSP with GST and pays the CPO, so the token’s party_id decides who receives the invoice. Outside India, the parties settle with each other peer to peer and the hub only reconciles kWh and amounts, without holding funds. The full path from CDR to payment is in EV roaming settlement. In India YoHub also offers UBC (Beckn) through the same connection as OCPI 2.2.1; UBC journeys use their own model and are outside the scope of this post.

Where token flows break, and how to fix them

Most token problems in production are not protocol bugs but sync and format gaps between two systems that each look correct:

SymptomLikely causeFix
Valid card rejected at one network onlyThe CPO never received the token: it connected after the eMSP’s last push, or a push failed and was not retried.Run a full GET on connection and an incremental pull by date_from on a schedule. Retry failed pushes.
Blocked card still chargesThe invalidating PATCH did not reach every CPO, and the token is ALWAYS-whitelisted.Confirm the PATCH per party, or use ALLOWED_OFFLINE where fast blocking matters.
Card works on one charger model, not anotherReaders report the RFID UID in different formats, such as byte order or length, so the read value does not match the pushed uid.Agree one UID format with each CPO and normalise on both sides. Note that uid is a case-insensitive string in OCPI.
App token “unknown” on lookupA GET or PUT was sent without ?type=, which defaults to RFID.Always send type for APP_USER and AD_HOC_USER tokens.
Session started with a key fob cannot be stopped with the cardgroup_id missing or longer than 20 characters, which OCPP 1.5 and 1.6 chargers cannot store.Keep group_id to 20 characters or fewer.
App start fails after a delay on one networkThe CPO re-authorises the command’s token, or ignores the timeout.Do not re-check START_SESSION tokens; respect the 15-minute RFID rule.

Common OCPI token failures, with causes and fixes based on the OCPI 2.2.1 Tokens and Commands modules.

A hub removes the first failure in the table: a new CPO syncs once against the hub instead of pulling from each eMSP, and its chargers then accept the credentials of every connected eMSP. On YoHub that means tokens usable across 75,000+ reachable stations worldwide, 14,000+ of them in India. The YoHub developer documentation covers the endpoints and onboarding.

If you run an eMSP or a charging app, the eMSP roaming page explains how one connection gets your tokens accepted across networks; CPOs can see the other side on the OCPI roaming page for CPOs.

Frequently Asked Questions

What is an OCPI token?

A record in the OCPI Tokens module representing a driver’s credential, such as an RFID card or app account. The eMSP owns it and shares it with CPOs so their chargers can authorise the driver and route the CDR back.

What is the difference between uid and contract_id in an OCPI token?

The uid is what the charger reads and is used to authorise. The contract_id is the driver’s contract at the eMSP, which the eMSP bills against. Both are carried into the Session and CDR.

Which whitelist type should an eMSP use?

The spec recommends NEVER for app and ad hoc tokens. For RFID cards, ALWAYS is most reliable offline, while ALLOWED_OFFLINE makes blocks take effect quickly and still allows charging when the eMSP is unreachable.

Should a CPO re-authorise the token in a START_SESSION command?

No. The eMSP authorises the token before sending START_SESSION, so the CPO must not check it again, and must not run a real-time authorisation for an RFID token within 15 minutes of the command.

How does a roaming hub handle OCPI tokens?

An eMSP sends one Broadcast Push to the hub, which forwards the token to every connected CPO implementing the Tokens module. Each token keeps its owner’s country_code and party_id.

Sources: OCPI 2.2.1 Tokens module | OCPI 2.2.1 Commands module | OCPI 2.2.1 Sessions module | OCPI 2.2.1 CDRs module | OCPI 2.2.1, Transport and format (Broadcast Push, routing) | EVRoaming Foundation, OCPI

Keep reading

More from the YoHub blog

Connect once. Reach every network.

Book a 45-minute call with the team that runs the platform. We'll map your integration and show you the network live.

Scroll to Top