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 tangible 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.

Reservation and Activation Flow

The Charging Key API is specific for Physical charging keys and uses a two-step process: Reservation and Activation.

Reserve a Charging Key

API Reference

Pre-registers a physical charging key (RFID) in the system by pairing the chip's unique identifier (uid) with a human-readable identifier (visualNumber).
This step prepares the key for future assignment (activation), but the key is not yet usable.
The uid should be in hexadecimal, little endian format.

Activate a Charging Key

API Reference

Links the reserved charging key to a specific user (userId), enabling it for authentication at charging stations.
Once activated, the key is fully functional and can be used for charging sessions.
A user can have multiple active keys, and keys can be enabled or disabled as needed.

Update Charging Key

API Reference

This endpoint allows to change the key name and disable / re-enable it.
When a charging key is disabled, it will immediately stop working on chargers.

Get Charging Keys

API Reference

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

Order Charging Key

API Reference

This endpoint allows you to order a charging key for a specific user.

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.

Get List of Ordered Charging Keys

API Reference

This endpoint returns the list of ordered charging keys by a given user.

Get URL to Charging Keys Order Receipt

API Reference

Returns an absolute URL to the receipt. You can check if the order has a receipt or not with the endpoint above.

Charging Keys Orders Configuration

API Reference

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