API docs by Redocly

OCPI 2.3.0 - Tokens Module - Receiver Interface (2.3.0)

Download OpenAPI specification:

URL: https://evroaming.org

The Receiver Interface (typically implemented by the CPO) allows the eMSP to push Token information to the CPO. Tokens are Client Owned Objects, so the endpoints contain the required extra fields: country_code, party_id and token_uid.

OCPI 2.3.0 Specification

Schemas

TokenType

string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

The type of token.

"AD_HOC_USER"

OCPIResponse

status_code
required
integer

OCPI status code, 1000 for success.

status_message
string

An optional status message which may help when debugging.

timestamp
required
string <date-time>

The time this message was generated.

data
any

Response data object or list of objects.

{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}

WhitelistType

string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Defines when authorization of a Token by the CPO is allowed.

"ALWAYS"

ProfileType

string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Different smart charging profile types.

"CHEAP"

EnergyContract

supplier_name
required
string <= 64 characters

Name of the energy supplier for this token.

contract_id
string <= 64 characters

Contract ID at the energy supplier, that belongs to the owner of this token.

{
  • "supplier_name": "string",
  • "contract_id": "string"
}

Token

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the MSP that 'owns' this Token.

party_id
required
string = 3 characters

ID of the eMSP that 'owns' this Token (following the ISO-15118 standard).

uid
required
string <= 36 characters

Unique ID by which this Token, combined with the Token type, can be identified. This is the field used by CPO system (RFID reader on the Charge Point) to identify this token. Currently, in most cases: type=RFID, this is the RFID hidden ID as read by the RFID reader, but that is not a requirement. If this is a APP_USER or AD_HOC_USER Token, it will be a uniquely, by the eMSP, generated ID. This field is named uid instead of id to prevent confusion with: contract_id.

type
required
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Type of the token

contract_id
required
string <= 36 characters

Uniquely identifies the EV Driver contract token within the eMSP's platform (and suboperator platforms). Recommended to follow the specification for eMA ID from "E-mobility ID-codes: the purpose of IDs, ID usage and ID format" (https://evroaming.org/contract-evse-ids/).

visual_number
string <= 64 characters

Visual readable number/identification as printed on the Token (RFID card), might be equal to the contract_id.

issuer
required
string <= 64 characters

Issuing company, most of the times the name of the company printed on the token (RFID card), not necessarily the eMSP.

group_id
string <= 36 characters

This ID groups a couple of tokens. This can be used to make two or more tokens work as one, so that a session can be started with one token and stopped with another, handy when a card and key-fob are given to the EV-driver. Beware that OCPP 1.5/1.6 only support group_ids (it is called parentId in OCPP 1.5/1.6) with a maximum length of 20.

valid
required
boolean

Is this Token valid

whitelist
required
string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Indicates what type of white-listing is allowed.

language
string = 2 characters

Language Code ISO 639-1. This optional field indicates the Token owner's preferred interface language. If the language is not provided or not supported then the CPO is free to choose its own language.

default_profile_type
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

The default Charging Preference. When this is provided, and a charging session is started on an Charge Point that support Preference base Smart Charging and support this ProfileType, the Charge Point can start using this ProfileType, without this having to be set via: Set Charging Preferences.

object (EnergyContract)

When the Charge Point supports using your own energy supplier/contract at a Charge Point, information about the energy supplier/contract is needed so the CPO knows which energy supplier to use. NOTE: In a lot of countries it is currently not allowed/possible to use a drivers own energy supplier/contract at a Charge Point.

last_updated
required
string <date-time>

Timestamp when this Token was last updated (or created).

{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string",
  • "valid": true,
  • "whitelist": "ALWAYS",
  • "language": "st",
  • "default_profile_type": "CHEAP",
  • "energy_contract": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

TokenPatch

country_code
string = 2 characters
party_id
string = 3 characters
uid
string <= 36 characters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

The type of token.

contract_id
string <= 36 characters
visual_number
string <= 64 characters
issuer
string <= 64 characters
group_id
string <= 36 characters
valid
boolean
whitelist
string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Defines when authorization of a Token by the CPO is allowed.

language
string = 2 characters
default_profile_type
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Different smart charging profile types.

object (EnergyContract)

Information about an energy contract that belongs to a Token so a driver could use his/her own energy contract when charging at a Charge Point.

last_updated
required
string <date-time>
{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string",
  • "valid": true,
  • "whitelist": "ALWAYS",
  • "language": "st",
  • "default_profile_type": "CHEAP",
  • "energy_contract": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

Tokens

Retrieve a Token

If the eMSP wants to check the status of a Token in the CPO system it might GET the object from the CPO system for validation purposes. The eMSP is the owner of the objects, so it would be illogical if the CPO system had a different status or was missing an object.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO that 'owns' this object (following the ISO-15118 standard).

token_uid
required
string <= 36 characters

Token.uid of the Token object.

query Parameters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Token.type of the Token to retrieve. Default if omitted: RFID

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Create or update a Token

New or updated Token objects are pushed from the eMSP to the CPO.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO that 'owns' this object (following the ISO-15118 standard).

token_uid
required
string <= 36 characters

Token.uid of the Token object.

query Parameters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Token.type of the Token to retrieve. Default if omitted: RFID

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required

New or updated Token object.

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the MSP that 'owns' this Token.

party_id
required
string = 3 characters

ID of the eMSP that 'owns' this Token (following the ISO-15118 standard).

uid
required
string <= 36 characters

Unique ID by which this Token, combined with the Token type, can be identified. This is the field used by CPO system (RFID reader on the Charge Point) to identify this token. Currently, in most cases: type=RFID, this is the RFID hidden ID as read by the RFID reader, but that is not a requirement. If this is a APP_USER or AD_HOC_USER Token, it will be a uniquely, by the eMSP, generated ID. This field is named uid instead of id to prevent confusion with: contract_id.

type
required
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Type of the token

contract_id
required
string <= 36 characters

Uniquely identifies the EV Driver contract token within the eMSP's platform (and suboperator platforms). Recommended to follow the specification for eMA ID from "E-mobility ID-codes: the purpose of IDs, ID usage and ID format" (https://evroaming.org/contract-evse-ids/).

visual_number
string <= 64 characters

Visual readable number/identification as printed on the Token (RFID card), might be equal to the contract_id.

issuer
required
string <= 64 characters

Issuing company, most of the times the name of the company printed on the token (RFID card), not necessarily the eMSP.

group_id
string <= 36 characters

This ID groups a couple of tokens. This can be used to make two or more tokens work as one, so that a session can be started with one token and stopped with another, handy when a card and key-fob are given to the EV-driver. Beware that OCPP 1.5/1.6 only support group_ids (it is called parentId in OCPP 1.5/1.6) with a maximum length of 20.

valid
required
boolean

Is this Token valid

whitelist
required
string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Indicates what type of white-listing is allowed.

language
string = 2 characters

Language Code ISO 639-1. This optional field indicates the Token owner's preferred interface language. If the language is not provided or not supported then the CPO is free to choose its own language.

default_profile_type
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

The default Charging Preference. When this is provided, and a charging session is started on an Charge Point that support Preference base Smart Charging and support this ProfileType, the Charge Point can start using this ProfileType, without this having to be set via: Set Charging Preferences.

object (EnergyContract)

When the Charge Point supports using your own energy supplier/contract at a Charge Point, information about the energy supplier/contract is needed so the CPO knows which energy supplier to use. NOTE: In a lot of countries it is currently not allowed/possible to use a drivers own energy supplier/contract at a Charge Point.

last_updated
required
string <date-time>

Timestamp when this Token was last updated (or created).

Responses

Request samples

Content type
application/json
{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string",
  • "valid": true,
  • "whitelist": "ALWAYS",
  • "language": "st",
  • "default_profile_type": "CHEAP",
  • "energy_contract": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}

Partially update a Token

Same as the PUT method, but only the fields/objects that have to be updated have to be present, other fields/objects that are not specified are considered unchanged. Any request to the PATCH method SHALL contain the last_updated field.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO that 'owns' this object (following the ISO-15118 standard).

token_uid
required
string <= 36 characters

Token.uid of the Token object.

query Parameters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Token.type of the Token to retrieve. Default if omitted: RFID

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required

Partial Token object with only the fields to update.

country_code
string = 2 characters
party_id
string = 3 characters
uid
string <= 36 characters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

The type of token.

contract_id
string <= 36 characters
visual_number
string <= 64 characters
issuer
string <= 64 characters
group_id
string <= 36 characters
valid
boolean
whitelist
string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Defines when authorization of a Token by the CPO is allowed.

language
string = 2 characters
default_profile_type
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Different smart charging profile types.

object (EnergyContract)

Information about an energy contract that belongs to a Token so a driver could use his/her own energy contract when charging at a Charge Point.

last_updated
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string",
  • "valid": true,
  • "whitelist": "ALWAYS",
  • "language": "st",
  • "default_profile_type": "CHEAP",
  • "energy_contract": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}