API docs by Redocly

OCPI 2.3.0 - Tokens Module - Sender Interface (2.3.0)

Download OpenAPI specification:

URL: https://evroaming.org

The Sender Interface (typically implemented by the eMSP) enables the Receiver to request the current list of Tokens. Via the POST method it is possible to authorize a single token in real-time.

OCPI 2.3.0 Specification

Schemas

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
}

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"

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"
}

LocationReferences

location_id
required
string <= 36 characters

Unique identifier for the location.

evse_uids
Array of strings[ items <= 36 characters ]

Unique identifiers for EVSEs within the CPO's platform for the EVSE within the given location.

{
  • "location_id": "string",
  • "evse_uids": [
    ]
}

AllowedType

string <enum> (AllowedType)
Enum Description
ALLOWED

This Token is allowed to charge (at this location).

BLOCKED

This Token is blocked.

EXPIRED

This Token has expired.

NO_CREDIT

This Token belongs to an account that has not enough credits to charge (at the given location).

NOT_ALLOWED

Token is valid, but is not allowed to charge at the given location.

Defines the allowed status of a Token.

"ALLOWED"

DisplayText

language
required
string = 2 characters

Language Code ISO 639-1.

text
required
string <= 512 characters

Text to be displayed to an end user. No markup, html etc. allowed.

{
  • "language": "st",
  • "text": "string"
}

AuthorizationInfo

allowed
required
string <enum> (AllowedType)
Enum Description
ALLOWED

This Token is allowed to charge (at this location).

BLOCKED

This Token is blocked.

EXPIRED

This Token has expired.

NO_CREDIT

This Token belongs to an account that has not enough credits to charge (at the given location).

NOT_ALLOWED

Token is valid, but is not allowed to charge at the given location.

Status of the Token, and whether charging is allowed at the optionally given location.

required
object (Token)

The complete Token object for which this authorization was requested.

object (LocationReferences)

Optional reference to the location if it was included in the request, and if the EV driver is allowed to charge at that location. Only the EVSEs the EV driver is allowed to charge at are returned.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.

object (DisplayText)

Optional display text, additional information to the EV driver.

{
  • "allowed": "ALLOWED",
  • "token": {
    },
  • "location": {
    },
  • "authorization_reference": "string",
  • "info": {
    }
}

Tokens

Get list of Tokens

Fetch information about Tokens known in the eMSP systems. If additional parameters date_from and/or date_to are provided, only Tokens with last_updated between the given date_from (including) and date_to (excluding) will be returned. This request is paginated.

Authorizations:
ocpiAuthorization
query Parameters
date_from
string <date-time>

Only return objects that have last_updated after or equal to this Date/Time (inclusive).

date_to
string <date-time>

Only return objects that have last_updated up to this Date/Time, but not including (exclusive).

offset
integer >= 0
Default: 0

The offset of the first object returned. Default is 0.

limit
integer >= 1

Maximum number of objects to GET.

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": [
    ]
}

Real-time authorization request

Do a 'real-time' authorization request to the eMSP system, validating if a Token might be used (at the optionally given Location).

When the eMSP does not know the Token, the eMSP SHALL respond with an HTTP status code: 404 (Not Found).

When the eMSP receives a 'real-time' authorization request from a CPO that contains too little information (no LocationReferences provided) to determine if the Token might be used, the eMSP SHALL respond with the OCPI status: 2002.

Authorizations:
ocpiAuthorization
path Parameters
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
optional

Optional LocationReferences object. The eMSP SHALL then validate if the Token is allowed to be used at this Location, and if applicable: which of the Location's EVSEs. The object with valid Location and EVSEs will be returned in the response.

location_id
required
string <= 36 characters

Unique identifier for the location.

evse_uids
Array of strings[ items <= 36 characters ]

Unique identifiers for EVSEs within the CPO's platform for the EVSE within the given location.

Responses

Request samples

Content type
application/json
{
  • "location_id": "string",
  • "evse_uids": [
    ]
}

Response samples

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