Skip to main content
Create, reserve, activate, and manage physical and virtual charging keys for Drive API users. The Charging Keys API enables the management of physical and virtual charging keys associated with users for EV charging authentication. This API allows you to:
  • Assign and activate a charging key for a user.
  • Disable or re-enable charging keys in case of loss or deactivation needs.
  • Retrieve a list of all activated charging keys for a specific user.

​
Charging key types

​
Physical charging key (RFID)

These are physical cards or tags equipped with an RFID chip used to authenticate at charging stations.
  • The identifier flashed on the chip is called uid. The uid is required in the reservation flow (which is unique to that type of key).
  • For physical charging keys, the uid is also the keyId.
  • The identifier printed on the card/tag is called visualNumber in the reservation flow, and referenceId later on.
  • When reserving a charging key, you can set the type field to either TAG or CARD. This has no practical implications.

​
Virtual charging keys

When creating a user, a charging key is automatically created and assigned to that user: it is what we call a virtual charging key.
  • The keyId of a virtual charging key is automatically generated when the key is created.
  • Virtual charging keys do not have referenceId.
  • They should not be displayed to users. A good practice is to filter them out by using the type field.

​
Plug&Charge keys

Plug&Charge keys enable the roaming of ISO 15118-based Plug&Charge sessions started at compatible charging stations. A Plug&Charge key is the roaming counterpart for the actual charging contract certificate that has been created for installation in the vehicle. Plug&Charge keys are mainly identified by their contractId (EMAID) and the Provisioning Certificate Identifier (PCID) representing the vehicle. The EMAID must match the actual charging contract certificate. The EMAID is encoded as the commonName (CN) attribute of the X.509 Subject Distinguished Name in the certificate and submitted to the charger on successful authorization.
  • The keyId of a Plug&Charge key is the contract identifier (in EMAID format).
  • The referenceId is the PCID of the vehicle.
  • Plug&Charge keys always use whitelist: NEVER — charging requires real-time authorization.
  • The type field value is plug_and_charge. Note that via OCPI 2.x we use OTHER as token type for such keys.
Plug&Charge keys are created via a dedicated endpoint. For the full guide including roaming details and information about the offered Plug&Charge solution via DriveAPI, see Plug&Charge.

​
Whitelist behavior

The whitelist property defines how a CPO may authorize a charging key when it cannot reach the EMP in real time. Possible values:
  • ALLOWED_OFFLINE: The CPO may allow charging offline if real-time authorization with the EMP is temporarily unavailable.
  • NEVER: The CPO should always rely on real-time authorization from the EMP and should not allow offline charging for this key.
The whitelist property is optional. If it is not provided, default will use ALLOWED_OFFLINE.

​
Charging Key Integration Options

Depending on your operational setup, the Drive API supports three different ways to create and assign physical charging keys. This section outlines the available integration flows, their use cases, and how to implement them.

​
Overview of Integration Options

​
Option 1: Order → Activation

Use this option when Plugsurfing handles product orders, manufacturing, and shipping directly to the end user.

​
When to Use

  • You use Plugsurfing’s PSP for payments.
  • You want Plugsurfing to manufacture and ship the charging key.

​
Flow

​
Steps

  1. Make the order (API Reference): Call POST /createChargingKeyOrder with the user ID, address, and payment option. To prevent duplicate orders, ordering charging keys for a single user is throttled to 1 order every 5 minutes. This is a safety measure to avoid accidental double-clicks on the order button, preventing the user from being charged twice. If the user exceeds this limit, a 429 - Too Many Requests HTTP response will be returned.
    Before using this endpoint, a manual configuration is required on the Plugsurfing side. Therefore, we ask you to reach out to us before using it.
  2. Manufacturing and shipping: Plugsurfing handles production and shipment.
  3. User activates the key(API Reference): User enters the referenceId in your app. You backend calls:

​
Option 2: Reservation → Activation

Use this when keys are produced in bulk and distributed without pre-assignment.

​
When to Use

  • You manage the production and distribution of charging keys
  • You don’t know in advance which user gets which key (keys are shipped without being linked to a user).

​
Steps

  1. Reserve the key (API Reference): Call POST /charging-keys/reservations or use Plusurfing’s CSV reservation import. Note that at that point, the charging key is not usable yet, it has to be activated. The uid should be in hexadecimal, little endian format.
  2. Ship the key: Partner handles distribution.
  3. User activates the key (API Reference): User enters the referenceId in your app. You backend should call
If you want to define how the CPO should authorize this key towards the EMP, include the whitelist field in the request body. This request body is optional, and the whitelist attribute is also optional. If it is not provided, default will use ALLOWED_OFFLINE. Use ALLOWED_OFFLINE if the CPO may allow charging when it cannot reach the EMP in real time, or NEVER if charging should always depend on real-time authorization.

​
Option 3: Direct Charging Key Creation

Use this when you know which user a charging key belongs to.

​
When to Use

  • You know the details of the charging keys and which users they belong to.
  • You want to import existing keys.

​
Steps

  1. Create the key directly (API Reference): Your backend should call
keyIdentifier, contractId, and referenceId are required.

​
Other Charging Key endpoints

​
Get Charging Keys API Reference

Returns a list of all activated charging keys of a given user.

​
Update Charging Key API Reference

Allows changing the key name and disabling / re-enabling it. When a charging key is disabled, it will immediately stop working on chargers.

​
Get List of Ordered Charging Keys API Reference

Returns the list of charging keys ordered by a given user.

​
Get URL to Charging Keys Order Receipt API Reference

Returns an absolute URL to the charging key order’s receipt. The receipt will be in PDF format.

​
Charging Keys Product Configuration API Reference

Returns the pricing information for charging key products per country. Each country has to be set up manually for your organization in order for it to show up here.