Charging Keys

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.

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

Feature	Option 1: Order → Activation	Option 2: Reservation → Activation	Option 3: Direct Charging Key Creation
Primary Use Case	Plugsurfing handles key manufacturing & shipping directly to the user upon order.	Keys are produced in bulk and distributed; the specific user is unknown until they activate the key.	Keys are assigned to specific, known users before shipment.
Plugsurfing Handles	Product Orders, Manufacturing, Shipping, Activation Processing, CPO Sharing	Key Data Reservation (UID/ReferenceID), Activation Processing, CPO Sharing	CPO Sharing
Partner Handles	Triggering the order via API	Ordering keys from manufacturer, Providing key data (CSV) for reservation, Shipping keys	Manufacturing/Sourcing keys, Shipping keys, Creating the keys on Plugsurfing side
Key Assignment Timing	When the end-user activates the key.	When the end-user activates the key.	Immediately when the partner creates the key via API.
Initial API Step	`POST /createChargingKeyOrder`	`POST /charging-keys/reservations` (or CSV import in our Reservation Tool)	`POST /users/{userId}/charging-keys`
Activation Method	User enters `referenceId` in app → triggers activate endpoint	User enters `referenceId` in app → triggers activate endpoint	No separate user activation needed, the key is created directly

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

sequenceDiagram
    participant User
    participant Your app
    participant Your backend
    participant Drive API


    User->>Your app: Order a charging key
    Your app->>Your backend: Create charging key
    Your backend->>Drive API: POST /createChargingKeyOrder
    Drive API->>Drive API: Manufacture the key
    Drive API->>User: Ship the key
    User->>Your app: Activate the key
    Your app->>Your backend: Activate
    Your backend->>Drive API: POST /users/{userId}/charging-keys/{referenceId}/activate

Steps

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.
Manufacturing and shipping:
Plugsurfing handles production and shipment.
User activates the key(API Reference):
User enters the referenceId in your app. You backend calls:

POST /users/{userId}/charging-keys/{referenceId}/activate

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

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.
Ship the key:
Partner handles distribution.
User activates the key (API Reference):
User enters the referenceId in your app. You backend should call

POST /users/{userId}/charging-keys/{referenceId}/activate

Option 3: Direct Charging Key Creation

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

When to Use

You assign keys to specific users in advance, before distributing them.
You want to import existing keys.

Steps

Create the key directly (API Reference):
Your backend should call

POST /users/{userId}/charging-keys

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.