OCPI Security and Authentication: Tokens, TLS & mTLS

OCPI is, in effect, a financial protocol. It moves invoices, energy readings, and user identifiers between parties — a CPO like Electrify America or IONITY and an eMSP like a mobility app — that may barely know each other. A single leaked credential can let an attacker push fake billing records or read another operator’s confidential session data. The security model itself is not complicated. The operational discipline around it is what separates a genuinely secure deployment from one that is only nominally compliant.

OCPI security and authentication come down to two things at the protocol layer: TLS for transport and a bearer token for identity. This article covers exactly how that model works, where the threat model actually lives, the real-world mistakes that compromise OCPI integrations, and how to build a defensible operational posture around it. If you want the wider protocol context first, see what OCPI is and how it differs from OCPP and ISO 15118, which secure different links in the same chain.

The OCPI security model in one paragraph

Every OCPI interaction is a TLS-encrypted HTTPS request carrying a bearer token in the Authorization header. The two parties exchanged these tokens during the Credentials handshake. The token authenticates the calling party. Trust in the token comes from the assumption that the token has not leaked. There is no per-request signing, no nonce mechanism, no challenge-response — the bearer token plus TLS is the whole security story for the protocol layer.

The header itself uses the literal scheme word Token, not Bearer:

Authorization: Token IpbJOXxkxOAuKR92z0nEcmVF3Qw09VG7I7d/WCg0koM=

One version detail worth knowing: in OCPI 2.2.1 the credentials token carried in that header is Base64-encoded, whereas 2.1.1 sent it verbatim. This changes how you store and compare tokens across versions, so it matters when you support both. For the full list of what changed between releases, see the OCPI version history.

This is intentionally simple. It’s also fragile if you don’t operate it carefully.

The Credentials handshake (the trust anchor)

Everything starts with the Credentials handshake, handled by the Credentials and Versions modules. The token exchange happens in three steps:

1. Out-of-band exchange of a registration token (token A). The party you are registering with (the receiver) generates token A and hands it to you through some channel outside OCPI — email, a partner portal, a Slack DM, sometimes a contract attachment.
2. First authenticated call uses token A to POST your own freshly generated real token (token B) to the partner’s /credentials endpoint. Token B is what they will use to authenticate to you from now on.
3. The partner responds with their real token (token C). From now on, you authenticate to them with token C; they authenticate to you with token B. Token A is single-use — the spec says it MAY no longer be used, so it is thrown away.

sequenceDiagram
    participant A as Party A
    participant B as Party B
    Note over A,B: B generates token A,<br/>hands it to A out-of-band
    A->>B: POST /credentials<br/>auth with token A<br/>body carries token B
    B-->>A: Returns token C
    Note over A,B: A stores token C<br/>B stores token B
    Note over A,B: Token A invalidated (single-use)
    A->>B: Future calls<br/>auth with token C
    B->>A: Future calls<br/>auth with token B

This is OCPI 2.2’s clean version. OCPI 2.1.1 has the same logic with less explicit naming. The cryptographic property: a party can’t masquerade as another without obtaining the real token, and the real token is exchanged only over already-authenticated TLS using a single-use registration token.

The handshake itself is fine. The operational discipline around it is where mistakes happen.

The threat model: what could go wrong

A short list of bad things that have happened in real OCPI deployments.

Token leakage via source code. Engineer commits a config file with the OCPI token to GitHub. Attacker scrapes GitHub for tokens, finds it, can now impersonate the party. Real, repeated occurrence in the industry.

Token leakage via logs. Token printed in application logs. Logs aggregated to a centralized log service. Anyone with log access can extract tokens. Especially bad if logs are shipped to a third-party SaaS without thinking about what’s in them.

Token reuse across environments. Production token used in staging by accident. Staging environment less secure. Attacker compromises staging, exfiltrates production token. Now they have production access.

Long-lived tokens. Token issued years ago, never rotated. Engineer who had access has since left the company. Multiple parties have access to that token. Forensic accountability gone.

Compromised TLS. Server uses old TLS versions or weak ciphers. Attacker performs MITM against the OCPI traffic. Stolen tokens, modified messages.

Endpoint authentication only, not authorization. Server accepts that the bearer token is valid (correctly identifies party X) but doesn’t check whether party X is allowed to do this specific thing. Result: any authenticated party can read or write anything.

Cross-party data leakage. Server logs Session details indiscriminately. A support engineer queries logs to debug an issue. Sees Sessions belonging to parties the engineer is not authorized to see.

Fake CDRs. Attacker with a leaked CPO token POSTs fake CDRs to an eMSP. eMSP bills its users for sessions that never happened. Reputation and financial damage.

Disabled partner that’s still issuing tokens. Partner relationship ended. Tokens never revoked. Partner’s old systems continue to send data, sometimes for months, sometimes deliberately.

The thread connecting most of these: operational discipline rather than protocol flaws.

The defense layers

A reasonably-secure OCPI deployment has several layers.

Layer 1: TLS done right

• TLS 1.2 minimum; TLS 1.3 strongly preferred.
• Modern cipher suites only (no RC4, no 3DES, no export ciphers, no plain CBC).
• Forward secrecy required (ECDHE or DHE key exchange).
• Server certificate from a real CA, properly chained, with HSTS enabled.
• Certificate pinning is overkill for OCPI in most cases (cert rotation gets messy) — rely on a well-managed PKI instead.
• Periodic SSL Labs (or similar) audit of your endpoints.

If you don’t get TLS right, nothing else matters. Bearer tokens flying over weak TLS are tokens about to leak.

Layer 2: Token management

• Generate tokens with sufficient entropy. Don’t roll your own; use a secure random source (32+ bytes of CSPRNG output, base64-encoded).
• Store tokens encrypted at rest. Database encryption, secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager, etc.). Never plaintext in app config.
• Never log full tokens. If you must log for debugging, log only the first 4-8 characters as an identifier.
• Rotate tokens on a schedule. Quarterly or biannually depending on your risk posture. OCPI’s Credentials PUT endpoint supports rotation; use it.
• Rotate on personnel changes. Engineer who had access leaves the team → rotate. Engineer changes role → rotate.
• Audit token access. Who in your organization can read the production tokens? Should be a short list. Reviewed quarterly.

Layer 3: Authentication AND authorization

Many implementations check that the bearer token is valid and stop there. The token tells you who is calling. It doesn’t tell you what they should be allowed to do.

A complete check:

• Is the token valid? (authentication)
• Is the calling party authorized to perform this specific action on this specific resource? (authorization)
• For Locations, is this party allowed to read this Location? (most are public to authenticated partners, but a CPO might restrict some)
• For Sessions/CDRs, is this party associated with this transaction? (a CPO should not be able to query CDRs from another CPO via your eMSP system)
• For Commands, is this party allowed to issue this command on this resource?

Without per-request authorization, a leaked token from any party gives access to everything.

Layer 4: Audit logging

• Log every OCPI request with: caller party ID, endpoint, method, response status, timestamp.
• Do NOT log: full tokens, full PII (user identifiers should be hashed or pseudonymized in logs), full energy data if not needed.
• Retain logs for at least 1 year (longer for regulated markets — Germany, for example, requires up to 10 years for billing-related records, and North American operators often align log retention with state utility-billing and tax rules such as California’s or the CRA’s multi-year record-keeping expectations).
• Monitor for anomalies: unusual volume from a partner, unusual endpoints, unusual error rates.
• Alert on security-relevant events: Credentials PUT (token rotation), authentication failures spike, unauthorized authorization attempts.

Layer 5: Network and infrastructure

• OCPI endpoints behind a WAF (Web Application Firewall). Helps with rate limiting, basic injection attacks, IP allowlisting if appropriate.
• Per-partner rate limits to prevent runaway loops or DoS attempts. See OCPI rate limiting and abuse protection ^{(coming soon)} for the details.
• IP allowlisting for partners with stable IP addresses (often hubs).
• Regular dependency scanning — your TLS library, your HTTP library, your framework all need to be patched.
• Network isolation — OCPI servers shouldn’t have direct access to non-OCPI internal systems beyond what they need (no direct database admin access, etc.).

Layer 6: Partner-side hygiene

Your security is only as strong as your weakest partner. Some things you can do (and ask of partners):

• Quarterly check-in on token rotation. Has the partner rotated their token recently?
• Incident notification agreements. If they have a breach, when do they tell you?
• Joint testing of revocation flows. Can you verify a revoked token stops working in their systems?
• Coordinated penetration testing. Annually, ideally bilateral with major partners.

Mutual TLS (mTLS): when and how

OCPI doesn’t require mTLS but it’s available as an additional security layer. With mTLS, both client and server present X.509 certificates and validate each other. The bearer token remains required; mTLS is an additional check.

Pros:

• Infrastructure-level identity verification, separate from the application-level token.
• Compromised token alone isn’t enough — attacker also needs the client certificate.
• Some compliance frameworks (regulated markets) prefer or require it.

Cons:

• Certificate lifecycle management (renewal, revocation, distribution) is operationally heavier.
• Many SaaS hubs don’t support mTLS easily.
• Adds complexity to partner onboarding.

Recommendation:

• For high-volume bilateral partnerships, mTLS is worth the operational overhead.
• For hub-mediated long-tail roaming, mTLS is usually impractical because the hub mediates many parties.
• Mixed deployments (mTLS for top partners, bearer-only for others) are common and reasonable.

The PII dimension

OCPI carries personal data. The Tokens module especially. User identifiers like RFID UIDs are personal data under Europe’s GDPR, and equally under North American regimes — California’s CCPA/CPRA and Canada’s PIPEDA both treat this kind of identifier as protected personal information. Session data is personal data. CDRs are personal data.

A complete security story includes:

• Data minimization. Only request the fields you actually need.
• Pseudonymization where possible. Hash user identifiers when storing for analytics.
• Data subject access requests. Be able to export or delete a user’s data on request — GDPR Articles 15-17 in the EU, and the equivalent access/deletion rights under CCPA/CPRA in California or PIPEDA in Canada.
• Cross-border data transfer compliance. If a CPO in the EU sends Sessions to an eMSP in the US, GDPR’s third-country transfer rules apply (SCCs, adequacy decisions). The reverse direction and intra-North-American flows carry their own obligations, so map data flows before you turn on a cross-border roaming partner.
• Retention limits. Don’t keep PII forever. Define a retention policy and enforce it.

This is partly an OCPI security problem and partly a broader data-protection problem, but OCPI integrations are a common vector for inadvertent PII handling.

Common operational mistakes (checklist)

A short checklist to audit your OCPI security posture against.

• All endpoints HTTPS, TLS 1.2+, modern cipher suites only.
• Tokens stored in a secrets manager, not in code or environment variables in plaintext.
• Tokens never appear in logs.
• Tokens rotated at least biannually.
• Per-request authorization, not just authentication.
• Audit logs retained 1+ year, monitored for anomalies.
• Partner offboarding procedure includes token revocation, verified.
• Annual penetration testing or security review of OCPI endpoints.
• mTLS evaluated for top partners.
• Data retention policy defined and enforced.

If you can check every box, you’re doing well. Most operators can’t check all of them. The list is a roadmap, not a pass/fail.

What an incident response looks like

If you suspect a compromise:

1. Rotate immediately. Don’t wait for confirmation; rotate the suspect token(s) right now.
2. Audit logs for unusual activity. Look for unusual endpoints accessed, unusual volumes, unfamiliar IP addresses.
3. Notify affected partners. If they sent you data via the compromised token, they need to know. Trust degrades fast without proactive communication.
4. Forensic review. Where did the token leak from? Source code commit? Compromised laptop? Misconfigured logging? Fix the root cause.
5. External notification. If PII was potentially exposed, regulators may need notification — the GDPR 72-hour rule in the EU, US state breach-notification laws (all 50 states have one), and Canada’s PIPEDA breach-reporting duty. Know which apply to your footprint before you need them.
6. Post-mortem. Document what happened, what you changed, how you’ll prevent recurrence.

Most operators have never had an OCPI incident. Most that do, find out about it from a partner or from log anomalies — not from a perpetrator’s confession. Plan accordingly.

The honest summary

OCPI’s protocol-layer security model is simple: TLS plus bearer tokens. The simplicity is fine. What fails is operational discipline — tokens that leak, infrastructure that’s misconfigured, partner relationships that aren’t cleanly offboarded. The best OCPI security investment is not new technology; it’s process and audit. Rotate your tokens, monitor your endpoints, train your engineers, and review your posture annually. Most “OCPI security incidents” are preventable with basic operational hygiene.