🎟️ Tokens & Authorization
OCPI uses tokens to identify and authorize EV drivers. Tokens can represent RFID cards, app users or other identifiers. The Tokens module synchronises whitelists between CPOs and eMSPs and supports on‑the‑fly authorizations.
Token object
A Token contains basic information about a customer:
| Field | Description |
|---|---|
uid | Unique identifier (up to 36 characters) used at the charge point to start a session. |
type | The token medium, e.g. RFID, APP_USER or OTHER. |
contract_id | Contract number linking the token to a user contract. |
issuer | Name of the issuing organisation (eMSP). |
valid | Whether the token is currently valid. |
last_updated | Timestamp of the last update. |
Tokens are exchanged via GET /tokens (pull) or POST /tokens/authorize (real‑time authorization). The real‑time authorize call may include LocationReferences to specify the location and connector; Gireve’s guide notes that LocationReferences are mandatory in POST /tokens/authorize requests【826352846409834†L1289-L1310】.
Whitelisting
In a roaming scenario the eMSP maintains the master list of tokens. It should push updates to its connected CPOs so that drivers can authenticate locally. When a token is updated or revoked, the eMSP performs a PUT or PATCH on the CPO’s Tokens receiver endpoint. A CPO may choose to pull tokens instead (pull model), but push is recommended for production systems【343458627312853†L1861-L1905】.
Real‑time authorization
If the CPO does not maintain a local whitelist, it can perform real‑time authorization by sending POST /tokens/authorize to the eMSP when a driver presents a token. The response indicates whether the token is allowed and may include an authorization_reference that must be stored on the session and CDR【343458627312853†L6224-L6334】. Direct Payment flows also rely on authorization references (see the Direct Payment section). If the CPO receives WHITELIST as the authorization method, it may cache the token for future sessions.
Remember to protect token data; the OCPI specification emphasises that no personal data beyond the token identifier and issuer should be exchanged.