Tokens

OCPI 2.2.1

By Abhishek Uniyal · Updated

Tokens in OCPI 2.2.1

A Token represents the identification used to authorize charging. Append the token UID and /authorize to the advertised Tokens endpoint. LocationReferences is optional. A request without it can succeed when the eMSP has enough information; the insufficient-information condition is not every missing request body. The later response includes a complete Token for a known token. An unknown token returns OCPI 2004 without data; insufficient location information requires 2002.

Sources (6)
country_code · CiString(2) · cardinality 1: ISO-3166 alpha-2 country code of the MSP that 'owns' this Token. party_id · CiString(3) · cardinality 1: ID of the eMSP that 'owns' this Token (following the ISO-15118 standard). uid · CiString(36) · cardinality 1: 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 · TokenType · cardinality 1: Type of the token contract_id · CiString(36) · cardinality 1: Uniquely identifies the EV Driver contract token within the eMSP's platform (and suboperator platforms). Recommended to follow the specification for eMA ID from "eMI3 standard version V1.0" (http://emi3group.com/documents-links/[http://emi3group.com/documents-links/]) "Part 2: business objects." visual_number · string(64) · cardinality ?: Visual readable number/identification as printed on the Token (RFID card), might be equal to the contract_id. issuer · string(64) · cardinality 1: Issuing company, most of the times the name of the company printed on the token (RFID card), not necessarily the eMSP. group_id · CiString(36) · cardinality ?: 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 · boolean · cardinality 1: Is this Token valid whitelist · WhitelistType · cardinality 1: Indicates what type of white-listing is allowed. language · string(2) · cardinality ?: 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 · ProfileType · cardinality ?: 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. energy_contract · EnergyContract · cardinality ?: 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 · DateTime · cardinality 1: Timestamp when this Token was last updated (or created).OCPI 2.2.1 Tokens module · #mod_tokens_token_objectallowed · AllowedType · cardinality 1: Status of the Token, and whether charging is allowed at the optionally given location. token · Token · cardinality 1: The complete Token object for which this authorization was requested. location · LocationReferences · cardinality ?: 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 · CiString(36) · cardinality ?: Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR. info · DisplayText · cardinality ?: Optional display text, additional information to the EV driver.OCPI 2.2.1 Tokens module · #mod_tokens_authorizationinfo_object"`{tokens_endpoint_url}{token_uid}/authorize[?type={type}]`"OCPI 2.2.1 Tokens module · #mod_tokens_post_method"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"OCPI 2.2.1 Tokens module · #mod_tokens_post_method"In the body an optional LocationReferences object can be given. The eMSP SHALL then validate if the Token is allowed to be used at this Location, and if applicable: which of the Locations EVSEs."OCPI 2.2.1 Tokens module · #mod_tokens_post_request_body"When the token is known by the Sender, the response SHALL contain a AuthorizationInfo object. If the token is not known, the response SHALL contain the status code: `2004: Unknown Token`, and no `data` field."OCPI 2.2.1 Tokens module · #mod_tokens_post_response_data

Example payload · bodiless-known-token-authorization

{
  "allowed": "ALLOWED",
  "token": {
    "uid": "EXAMPLE-TOKEN",
    "type": "RFID",
    "issuer": "Example Provider",
    "valid": true,
    "whitelist": "NEVER",
    "last_updated": "2026-01-01T00:00:00Z",
    "country_code": "NL",
    "party_id": "EXB",
    "contract_id": "EXAMPLE-CONTRACT"
  }
}

Example payload · insufficient-location-envelope

{
  "status_code": 2002,
  "timestamp": "2026-01-01T00:00:00Z"
}

Example payload · unknown-token-envelope

{
  "status_code": 2004,
  "timestamp": "2026-01-01T00:00:00Z"
}
Read token authorization in the charging lesson

Which endpoints does this module define?

These paths illustrate the requests. Use the URLs advertised by your partner, replace the placeholders and choose the matching interface. A listed method does not establish that this site's simulator implements it.

CPO · receiver interface

  • Retrieve a Token as it is stored in the CPO system.

    GET
    /ocpi/2.2.1/tokens/{country_code}/{party_id}/{token_uid}
  • Push new/updated Token object to the CPO.

    PUT
    /ocpi/2.2.1/tokens/{country_code}/{party_id}/{token_uid}
  • Notify the CPO of partial updates to a Token.

    PATCH
    /ocpi/2.2.1/tokens/{country_code}/{party_id}/{token_uid}
Source
Method: Description GET: Retrieve a Token as it is stored in the CPO system. POST: n/a PUT: Push new/updated Token object to the CPO. PATCH: Notify the CPO of partial updates to a Token. DELETE: n/a, (Use PUT, Tokens cannot be removed).OCPI 2.2.1 Tokens module · #mod_tokens_cpo_interface

eMSP · sender interface

  • Get the list of known Tokens, last updated between the {date_from} and {date_to} (paginated)

    GET
    /ocpi/2.2.1/tokens/
  • Real-time authorization request

    POST
    /ocpi/2.2.1/tokens/{token_uid}/authorize
Source
Method: Description GET: Get the list of known Tokens, last updated between the {date_from} and {date_to} (paginated) POST: Real-time authorization request PUT: n/a PATCH: n/a DELETE: n/aOCPI 2.2.1 Tokens module · #mod_tokens_emsp_interface

Try an endpoint

Send a request to this site's OCPI endpoints and read the answer. It never reaches your own system.