Session Lifecycle

This page describes the complete session path from authorization through CDR delivery. For role-specific endpoints and checklists, see the CPO and eMSP integration guides.

The sequence below is the default via-Hub path: authorize, commands, sessions, and CDRs all traverse the Hub.

Sequence diagram

Step-by-step

1. Token authorization

The eMSP authorizes the driver's token before charging:

eMSP → Hub: PUT /ocpi/2.2.1/tokens/{emsp_cc}/{emsp_pid}/{token_uid}/authorize
Hub → CPO:  PUT /ocpi/2.2.1/tokens/{emsp_cc}/{emsp_pid}/{token_uid}/authorize

The CPO responds with ALLOWED, BLOCKED, NOT_ALLOWED, or UNKNOWN. The Hub returns this to the eMSP.

2. Start session

The eMSP sends a remote start command:

eMSP → Hub: POST /ocpi/2.2.1/commands/START_SESSION
Hub → CPO:  POST /ocpi/2.2.1/commands/START_SESSION

Required fields:

response_url - where async results are delivered (Hub rewrites CPO callback)
token - driver token object
location_id, evse_uid, connector_id - target charge point

3. Session becomes active

The CPO pushes session state to Hub:

CPO → Hub: PUT /ocpi/2.2.1/sessions/{cpo_cc}/{cpo_pid}/{session_id}

The session must include cdr_token identifying the eMSP. The Hub asynchronously pushes to the eMSP:

Hub → eMSP: PUT /ocpi/2.2.1/sessions/{cpo_cc}/{cpo_pid}/{session_id}

4. Stop session

The eMSP sends stop:

eMSP → Hub: POST /ocpi/2.2.1/commands/STOP_SESSION

Include session_id in the command body.

5. Session completed

The CPO pushes final session state (COMPLETED) to Hub, which forwards to eMSP asynchronously.

6. CDR delivery

The CPO posts the CDR:

CPO → Hub: POST /ocpi/2.2.1/cdrs
Hub → eMSP: POST /ocpi/2.2.1/cdrs (async)

Required fields summary

Field	Set by	Purpose
`cdr_token.country_code`	CPO on session/CDR	Routes async delivery to eMSP
`cdr_token.party_id`	CPO on session/CDR	Routes async delivery to eMSP
`response_url`	eMSP on command	Async command result delivery
`session_id`	CPO / command flow	Links stop command to active session

Timing expectations

Path	Type	Target latency
Token authorize	Realtime	Synchronous (CPO response time)
Commands	Realtime + async	Immediate accept/reject; async result via callback
Sessions	Async push	p95 < 5 seconds (Hub → eMSP)
CDRs	Async push	p95 < 5 seconds (Hub → eMSP)

See Async Delivery for retry behavior.

Common failures

Failure	Cause
Authorization `UNKNOWN`	CPO unreachable or token not recognized
Command `REJECTED`	EVSE unavailable, invalid location, or routing not configured
Session not received by eMSP	Missing `cdr_token` or eMSP receiver URL not configured
CDR not received	Same as session - check `cdr_token` and receiver URL

See Troubleshooting for a broader symptom index.

Role-specific next steps

Role	What to implement
CPO	Sessions · CDRs · Tokens · Commands · Hub Receiver Identity
eMSP	Tokens · Commands · Sessions · CDRs · Hub Receiver Identity · Async Delivery