Authentication

All OCPI requests to ChargeIndia Hub require authentication unless explicitly noted otherwise.

Request authentication

Include the OCPI credentials token in every request. Per OCPI 2.2.1, the header value is Base64(UTF-8(raw-token)) (RFC 4648):

Authorization: Token {base64-utf8-of-your-token}

Example: if the Credentials exchange gave you the raw token example-token, send:

Authorization: Token ZXhhbXBsZS10b2tlbg==

Store the raw token from credentials exchange securely. Treat it as a secret comparable to an API key. Only Base64-encode it when placing it in the Authorization header.

Legacy raw headers

While a party is in COMPATIBILITY, the Hub accepts both Base64 and raw (non-Base64) tokens in Authorization. After the party is COMPLIANT, Base64 is required unless ops enables Accept raw token on that party (Credentials tab). New integrations should send Base64 as required by OCPI 2.2.1.

Auth on all OCPI routes

ChargeIndia Hub requires authentication on all /ocpi/* routes, including GET /ocpi/versions. This differs from some OCPI implementations that expose versions without auth.

Tracing headers

The Hub accepts optional tracing headers:

Header	Purpose
`X-Request-ID`	Unique ID for this request
`X-Correlation-ID`	ID linking related requests across parties

If omitted, the Hub generates values automatically. Include them in your logs for support investigations.

Message routing headers (OCPI 2.2.1)

On functional modules (Commands, Tokens, Locations, Sessions, CDRs, Tariffs, etc.), OCPI 2.2.1 Message Routing uses four optional headers:

Header	Purpose
`OCPI-from-country-code`	Country code of the requesting party
`OCPI-from-party-id`	Party id of the requesting party
`OCPI-to-country-code`	Country code of the intended destination
`OCPI-to-party-id`	Party id of the intended destination

Hub behavior:

OCPI-from-*: optional. If present, both halves must be set and must match the party authenticated by Authorization. Mismatch → HTTP 401, status_message indicates from-header mismatch.
OCPI-to-*: optional (Open Routing when omitted). If present, both halves must be set; Hub validates against the destination resolved from body/path (e.g. location_id for START_SESSION, path peer for authorize). Conflict → HTTP 400.
Hub always emits OCPI-from-* / OCPI-to-* on Hub→partner forwards for functional modules.
Hub sets swapped routing headers on functional-module responses.

Do not send routing headers on configuration modules: Credentials, Versions, HubClientInfo. The Hub ignores them there.

See Routing for the commercial allow-list (separate from these headers).

Response envelope

All Hub responses use the standard OCPI envelope:

{
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2025-06-23T10:00:00.000Z",
  "data": { }
}

status_code	Meaning
`1000`	Success
`2000`	Generic client error (includes auth failures with HTTP `401`)
`2001`	Invalid or missing parameters
`2002`	Not enough information
`2003`	Unknown Location
`2004`	Unknown Token
`2901`	Rate limit exceeded (Hub)
`3002`	Unsupported OCPI version
`4001`–`4003`	Hub routing / peer errors

Suspended parties

If your party account is suspended, all authenticated requests return 401 with status_code: 2000. Contact your account team to resolve.

Outbound calls (Hub → your platform)

When the Hub calls your OCPI endpoints, it uses the raw token you provided during credentials exchange, Base64-encoded in the header per OCPI 2.2.1:

Authorization: Token {base64-utf8-of-token-you-provided}

Your platform must validate by decoding Base64 against the token from the Credentials object. If your platform still compares the header to the raw token, ChargeIndia ops can enable Send raw token on your party (Credentials tab). That switch is per party and does not retry both encodings.

Command callbacks

Async command results require CPO authentication (same OCPI Token scheme as other Hub routes). You must own the command:

POST /ocpi/2.2.1/commands/callback/{command_id}
Authorization: Token {cpo-token}

Hub forwards the result to the eMSP response_url. See Commands (CPO).

Onboarding - how tokens are issued
Token rotation - rotating credentials safely