Internal Tokens (beta)

No OAuth-enabled endpoints in this section. Turn off the OAuth filter in the sidebar to see all of its endpoints.

An internal token is authorisation media — an RFID card or an EVCCID (plug & charge identifier) — that you as the operator issue and authorise yourself, without it belonging to a mobility service provider. Typical use is a staff, installer or test card, or a single card that should charge for free at your own chargers.

Do not confuse this group with Tokens, which manages the tokens issued to mobility customers by an MSP. Internal tokens never leave your own platform: they are stored per provider, and authorisation for them is decided locally instead of being sent to a roaming network.

How they are used

Create the token with the uid printed on (or read from) the card.
Create a customer group with a filter of type INTERNAL_TOKEN whose value is the token's id — the generated UUID returned here, not the uid. This is the single most common mistake in this flow.
Reference that customer group from a charging policy tariff rule to give the card its own price.

At authorisation, a presented UID is checked against your internal tokens first; only if it is not one of them is it offered to the roaming network. A blocked or expired internal token is rejected outright rather than falling through to roaming. A token with hasInstallerAccess is additionally allowed to charge at stations that are not yet fully commissioned, because the usual charging station readiness checks are skipped for it.

These endpoints are governed by the chargingPolicies permission scope (chargingPolicies:read for search, chargingPolicies:write for everything else) — there is no separate internal token scope.

This API is in preview. It is functional and safe to build against, but breaking changes may still occur; any breaking change is announced in advance.

POST/1/internal-tokens

Create Internal Token

Registers a card or plug & charge identifier as authorisation media of the current provider and returns its id. uid is the identifier the charging station reports (the card number for RFID, the EVCCID for EVCCID), and reference is a free-text label for your own administration. The token is active immediately, but it grants nothing until a customer group with an INTERNAL_TOKEN filter on the returned id is referenced by a charging policy. Use the returned id in that filter, not the uid.

Authorization

User sessionAPI credential

Permissions

charging-policies:write

OAuth

Request

Request bodyapplication/json

expiresAtstring <date-time> | null

hasInstallerAccessboolean

default false

referencestring

default

typestringREQUIRED

EVCCIDRFID

uidstringREQUIRED

Responses

201OK text/plain

Returns a file (Text).

400Invalid Request application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

401Unauthorized application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

403Forbidden: missing a required permission, or no access to this resource application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

404Not Found application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

500Internal server error application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

POST/1/internal-tokens/search

Search Internal Tokens

Returns a paginated list of internal tokens for the current provider, filtered by ids or a free-text query over the uid and reference. Set format to csv to stream the result as a semicolon-delimited CSV attachment instead of JSON; CSV exports are capped and a request matching too many rows is rejected, so narrow the filters first.

Authorization

User sessionAPI credential

Permissions

charging-policies:read

OAuth

Request

Request bodyapplication/json

filenamestring

default internal-tokens.csv

formatstring

csvjson

default json

idsstring[]

limitinteger

default 50min 1

querystring

skipinteger

default 0min 0

Responses

200OK application/json

dataInternalToken[]

accountobject

idstringREQUIRED

namestringREQUIRED

accountIdstring

Account the token is assigned to, for session attribution. Does not affect which tariff applies.

createdAtstring <date-time>REQUIRED

expiresAtstring <date-time>

hasInstallerAccessbooleanREQUIRED

Installer pass: authorisation skips the charging station readiness checks.

idstringREQUIRED

Reference this id from a customer group filter of type INTERNAL_TOKEN, not the uid.

isBlockedbooleanREQUIRED

A blocked token is rejected at authorisation and is not offered to the roaming network.

providerIdstringREQUIRED

referencestringREQUIRED

Free-text label for the operator's own administration.

typestringREQUIRED

EVCCIDRFID

uidstringREQUIRED

The identifier the charging station reports: the card number for RFID, the EVCCID for EVCCID.

updatedAtstring <date-time>REQUIRED

metaobject

limitnumber

skipnumber

statsobject

totalnumber

400Invalid Request application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

401Unauthorized application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

403Forbidden: missing a required permission, or no access to this resource application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

404Not Found application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

500Internal server error application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

PUT/1/internal-tokens/{id}

Update Internal Token

Updates the mutable properties of an internal token: its reference, whether it carries installer access, and its expiry (null for no expiry). The uid and type are fixed at creation — to re-key a card, delete the token and create a new one. This is a full replace, so send the complete set of values: an omitted reference is reset to empty, an omitted hasInstallerAccess to false, and an omitted expiresAt clears the expiry.

Authorization

User sessionAPI credential

Permissions

charging-policies:write

OAuth

Request

Path parameters1

idstringREQUIRED

Request bodyapplication/json

expiresAtstring <date-time> | null

hasInstallerAccessboolean

default false

referencestring

default

Responses

204OK text/plain

Returns a file (Text).

400Invalid Request application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

401Unauthorized application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

403Forbidden: missing a required permission, or no access to this resource application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

404Not Found application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

500Internal server error application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

DELETE/1/internal-tokens/{id}

Delete Internal Token

Permanently removes the token. Customer groups that reference its id are left in place and simply stop matching, so remember to clean them up. Prefer blocking for anything reversible.

Authorization

User sessionAPI credential

Permissions

charging-policies:write

OAuth

Request

Path parameters1

idstringREQUIRED

Responses

204OK text/plain

Returns a file (Text).

400Invalid Request application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

401Unauthorized application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

403Forbidden: missing a required permission, or no access to this resource application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

404Not Found application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

500Internal server error application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

POST/1/internal-tokens/{id}/assign

Assign Internal Token

Assigns the token to one of your accounts, so sessions authorised with it are attributed to that account. This does not affect which tariff applies: that is decided by customer groups, and an internal token is only ever matched by an INTERNAL_TOKEN filter, never by an ACCOUNT filter.

Authorization

User sessionAPI credential

Permissions

charging-policies:write

OAuth

Request

Path parameters1

idstringREQUIRED

Request bodyapplication/json

accountIdstringREQUIRED

Responses

204OK text/plain

Returns a file (Text).

400Invalid Request application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

401Unauthorized application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

403Forbidden: missing a required permission, or no access to this resource application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

404Not Found application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

500Internal server error application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

POST/1/internal-tokens/{id}/block

Block Internal Token

Blocks the token: any session started with it is rejected from the next authorisation onwards, and the UID is not offered to the roaming network as a fallback. Reversible with the unblock endpoint — use this rather than deletion for a card that is temporarily out of use, lost or being investigated.

Authorization

User sessionAPI credential

Permissions

charging-policies:write

OAuth

Request

Path parameters1

idstringREQUIRED

Responses

204OK text/plain

Returns a file (Text).

400Invalid Request application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

401Unauthorized application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

403Forbidden: missing a required permission, or no access to this resource application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

404Not Found application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

500Internal server error application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

POST/1/internal-tokens/{id}/unblock

Unblock Internal Token

Lifts a block, so the token authorises sessions again under the policies that apply to it. Has no effect on an expired token.

Authorization

User sessionAPI credential

Permissions

charging-policies:write

OAuth

Request

Path parameters1

idstringREQUIRED

Responses

204OK text/plain

Returns a file (Text).

400Invalid Request application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

401Unauthorized application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

403Forbidden: missing a required permission, or no access to this resource application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

404Not Found application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED

500Internal server error application/json

errorobject

detailsobject

messagestringREQUIRED

statusnumberREQUIRED

typestringREQUIRED