> ## Documentation Index
> Fetch the complete documentation index at: https://developer.plugsurfing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Charging Keys

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](/docs/drive-api/plug-and-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

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

```mermaid theme={null}
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

1. **Make the order** ([**API Reference**](/reference/createChargingKeyOrder)):
   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.

   <Warning>
     Before using this endpoint, a manual configuration is required on the Plugsurfing side. Therefore, we ask you to **[reach out to us](/contact-and-support)** before using it.
   </Warning>

2. **Manufacturing and shipping**:
   Plugsurfing handles production and shipment.

3. **User activates the key**([**API Reference**](/reference/activateUserChargingKey)):
   User enters the `referenceId` in your app. You backend calls:

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

<br />

### 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**](/reference/createChargingKeyReservation)):
   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**](/reference/activateUserChargingKey)):
   User enters the `referenceId` in your app. You backend should call

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

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.

<br />

### 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**](/reference/createUserChargingKey)):
   Your backend should call

```
POST /users/{userId}/charging-keys
```

`keyIdentifier`, `contractId`, and `referenceId` are required.

## Other Charging Key endpoints

### Get Charging Keys [**API Reference**](/reference/listUserChargingKeys)

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

### Update Charging Key [**API Reference**](/reference/updateUserChargingKey)

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**](/reference/listChargingKeyOrders)

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

### Get URL to Charging Keys Order Receipt [**API Reference**](/reference/getChargingKeyOrderReceiptUrl)

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

### Charging Keys Product Configuration [**API Reference**](/reference/getChargingKeyOrderConfiguration)

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.