OCPI 2.3.0 Chapter 7

Credentials Module

The credentials module is used to exchange the credentials token that has to be used by parties for authorization of requests. Every OCPI request is required to contain a credentials token in the HTTP Authorization header.

5 Sections
4 HTTP Methods
6 Use Cases

1. Overview

Introduction

The credentials module is used to exchange the credentials token that has to be used by parties for authorization of requests. Every OCPI request is required to contain a credentials token in the HTTP Authorization header.

About the Module

Module Identifier

credentials

Module Type

Configuration Module

Symmetric

This module must be implemented by all OCPI implementations and all implementations need to be able to call this module on any other platform.

Authorization

Every OCPI request requires a credentials token in the HTTP Authorization header for authenticating requests between platforms.

Token Exchange

The credentials module facilitates the exchange of credentials tokens between platforms. During registration, three tokens are involved: CREDENTIALS_TOKEN_A (initial token created by the Receiver), CREDENTIALS_TOKEN_B (generated by the Sender and sent to the Receiver), and CREDENTIALS_TOKEN_C (generated by the Receiver and returned to the Sender). After registration completes, only CREDENTIALS_TOKEN_B and CREDENTIALS_TOKEN_C remain in use. Due to its symmetric nature, any platform can be Sender and/or the Receiver for this module.

2. Use Cases

Section 7.1
7.1.1

Registration

Initial exchange of credentials tokens between platforms to start using OCPI.

To start using OCPI, the Platforms will need to exchange credentials tokens. To start the exchange of credentials tokens, one platform has to be selected as Sender for the Credentials module. This has to be decided between the Platforms (outside of OCPI) before they first connect.

To start the credentials exchange, the Receiver Platform must create a unique credentials token: CREDENTIALS_TOKEN_A that has to be used to authorize the Sender until the credentials exchange is finished. This credentials token along with the versions endpoint SHOULD be sent to the Sender in a secure way that is outside the scope of this protocol.

The Sender starts the registration process, retrieves the version information and details (using CREDENTIALS_TOKEN_A in the HTTP Authorization header). The Sender generates a unique credentials token: CREDENTIALS_TOKEN_B, sends it to the Receiver in a POST request to the credentials module of the Receiver. The Receiver stores CREDENTIALS_TOKEN_B and uses it for any requests to the Sender Platform, including the version information and details.

The Receiver generates a unique credentials token: CREDENTIALS_TOKEN_C and returns it to the Sender in the response to the POST request from the Sender.

After the credentials exchange has finished, the Sender SHALL use CREDENTIALS_TOKEN_C in future OCPI request to the Receiver Platform. The CREDENTIALS_TOKEN_A can then be thrown away, it MAY no longer be used.

Note: In the sequence diagrams below we use relative paths as short resource identifiers to illustrate API endpoints; please note that they should be absolute URLs in any working implementation of OCPI.
Registration Sequence 
Sender                                          Receiver
  |                                                |
  |              [Offline]                         |
  |                                                |
  |    <--- Generate token: CREDENTIALS_TOKEN_A    |
  |                                                |
  |  send information via e-mail                   |
  |  (CREDENTIALS_TOKEN_A,                         |
  |   "https://company.com/ocpi/cpo/versions", ..) |
  |                                                |
  |              [OCPI]                            |
  |                                                |
  |  GET /ocpi/cpo/versions ------------------>    |
  |  (using CREDENTIALS_TOKEN_A)                   |
  |    <-------------- Available versions          |
  |                                                |
  |  Pick latest mutual version (e.g. 2.2)         |
  |                                                |
  |  GET /ocpi/cpo/2.2 ---------------------->     |
  |    <-------------- Available endpoints for v2.2|
  |                                                |
  |  Store version and endpoints                   |
  |                                                |
  |  Generate token: CREDENTIALS_TOKEN_B           |
  |                                                |
  |  POST /ocpi/cpo/2.2/credentials ---------->    |
  |  ("/ocpi/emsp/versions", CREDENTIALS_TOKEN_B)  |
  |                                                |
  |  [Receiver does NOT directly respond]          |
  |  [Receiver first fetches Sender versions]      |
  |                                                |
  |                     Store CREDENTIALS_TOKEN_B  |
  |                                                |
  |    <------------ GET /ocpi/emsp/versions       |
  |  Available versions ---------------------->    |
  |    <------------ GET /ocpi/emsp/2.2            |
  |  Available endpoints for v2.2 ------------>    |
  |                                                |
  |                 Store version and endpoints    |
  |                                                |
  |                 Generate CREDENTIALS_TOKEN_C   |
  |                                                |
  |    <--- Credentials with CREDENTIALS_TOKEN_C   |
  |         (response to the POST above)           |
  |                                                |
  |  Store updated credentials with                |
  |  CREDENTIALS_TOKEN_C                           |
  |                                                |

Registration Flow Steps:

  1. [Offline] Receiver generates CREDENTIALS_TOKEN_A and sends it to Sender via secure channel (e.g., email)
  2. Sender fetches Receiver's versions endpoint using CREDENTIALS_TOKEN_A
  3. Sender picks the latest mutually supported version
  4. Sender fetches version details to discover available endpoints
  5. Sender stores the version and endpoints
  6. Sender generates CREDENTIALS_TOKEN_B
  7. Sender POSTs credentials to Receiver (includes versions URL and CREDENTIALS_TOKEN_B)
  8. Receiver stores CREDENTIALS_TOKEN_B and fetches Sender's versions and endpoints
  9. Receiver generates CREDENTIALS_TOKEN_C and returns it in the POST response
  10. Sender stores CREDENTIALS_TOKEN_C for future requests to Receiver

Due to its symmetric nature of the credentials module, any platform can be Sender and/or the Receiver for this module.

7.1.2

Updating to a Newer Version

Switching to a newer OCPI version when both platforms have implemented it.

At some point, both platforms will have implemented a newer OCPI version. To start using the newer version, one platform has to send a PUT request to the credentials endpoint of the other platform.

Update Sequence 
Sender                                          Receiver
  |                                                |
  |  GET /ocpi/cpo/versions ------------------>    |
  |    <-------------- Available versions          |
  |                                                |
  |  Pick latest mutual version (e.g. 2.0)         |
  |                                                |
  |  GET /ocpi/cpo/2.0/ --------------------->     |
  |    <-------------- Available endpoints for v2.0|
  |                                                |
  |  Store version and endpoints                   |
  |                                                |
  |  PUT /ocpi/cpo/2.0/credentials ----------->    |
  |                                                |
  |    <------------ GET /ocpi/emsp/versions       |
  |  Available versions ---------------------->    |
  |    <------------ GET /ocpi/emsp/2.0/           |
  |  Available endpoints for v2.0 ------------>    |
  |                                                |
  |                 Store version and endpoints    |
  |                                                |
  |    <--- Return updated credentials for Sender  |
  |                                                |
  |  Store updated credentials                     |
  |                                                |

Update Flow Steps:

  1. Sender fetches Receiver's available versions
  2. Sender picks the latest mutually supported version
  3. Sender fetches version details for the selected version
  4. Sender stores the new version and endpoints
  5. Sender sends PUT to credentials endpoint of the new version
  6. Receiver fetches Sender's versions and endpoints
  7. Receiver stores the updated version and endpoints
  8. Receiver returns updated credentials to Sender
  9. Sender stores the updated credentials
7.1.3

Changing Endpoints for the Current Version

Updating endpoints without changing the OCPI version.

This can be done by following the update procedure for the same version. By sending a PUT request to the credentials endpoint of this version, the other platform will fetch and store the corresponding set of endpoints.

The procedure is identical to updating to a newer version (7.1.2), except you send the PUT request to the credentials endpoint of the current version rather than a new one. The receiving platform will re-fetch and store the updated endpoints.

7.1.4

Updating the Credentials and Resetting the Credentials Token

Refreshing credentials and tokens, including for security purposes.

The credentials (or parts thereof, such as the credentials token) can be updated by sending the new credentials via a PUT request to the credentials endpoint of the current version, similar to the update procedure described above.

Security advices: When one of the connecting platforms suspects that a credentials token is compromised, that platform SHALL initiate a credentials token update as soon as possible. It is advisable to renew the credentials tokens at least once a month, in case it was not detected that the credentials were compromised.
7.1.5

Errors During Registration

Handling problems that occur when the server connects back to the client.

When the server connects back to the client during the credentials registration, it might encounter problems. When this happens, the server should add the status code 3001 in the response to the POST from the client.

Error Status Code
3001 Unable to use the client's API. Not providing a valid response to the server's request during registration.
7.1.6

Required Endpoints Not Available

Handling the case when expected endpoints are missing on the other platform.

When two platforms connect, it might happen that one of the platforms expects a certain endpoint to be available at the other platform. For example: a Platform with a CPO role could only want to connect when the CDRs endpoint is available in a platform with an eMSP role.

Sender Behavior

In case the Sender (starting the credentials exchange process) cannot find the endpoints it expects, it is expected NOT to send the POST request with credentials to the Receiver. Log a message/notify the administrator to contact the administrator of the Receiver platform.

Receiver Behavior

In case the Receiver platform cannot find the endpoints it expects, then it is expected to respond to the request with the status code 3003.

Error Status Codes
3003 Unable to use the client's API. Required endpoints are not available.

3. Interfaces & Endpoints

Section 7.2

The Credentials module is different from all other OCPI modules. This module is symmetric, it has to be implemented by all OCPI implementations, and all implementations need to be able to call this module on any other platform, and have to be able to handle receiving the request from another party.

Endpoint Overview

Example: /ocpi/2.2.1/credentials and /ocpi/emsp/2.2.1/credentials

Method Description
GET Retrieves the credentials object to access the server's platform.
POST Provides the server with a credentials object to access the client's system (i.e. register).
PUT Provides the server with an updated credentials object to access the client's system.
PATCH n/a
DELETE Informs the server that its credentials to the client's system are now invalid (i.e. unregister).

7.2.1. GET Method

GET Retrieve credentials

Retrieves the credentials object to access the server's platform. The request body is empty, the response contains the credentials object to access the server's platform. This credentials object also contains extra information about the server such as its business details.

7.2.2. POST Method

POST Register credentials

Provides the server with credentials to access the client's system. This credentials object also contains extra information about the client such as its business details.

A POST initiates the registration process for this endpoint's version. The server must also fetch the client's endpoints for this version.

If successful, the server must generate a new credentials token and respond with the client's new credentials to access the server's system. The credentials object in the response also contains extra information about the server such as its business details.

Important: This method MUST return a HTTP status code 405: method not allowed if the client has already been registered before.

7.2.3. PUT Method

PUT Update credentials

Provides the server with updated credentials to access the client's system. This credentials object also contains extra information about the client such as its business details.

A PUT will switch to the version that contains this credentials endpoint if it's different from the current version. The server must fetch the client's endpoints again, even if the version has not changed.

If successful, the server must generate a new credentials token for the client and respond with the client's updated credentials to access the server's system. The credentials object in the response also contains extra information about the server such as its business details.

Important: This method MUST return a HTTP status code 405: method not allowed if the client has not been registered yet.

7.2.4. DELETE Method

DELETE Unregister credentials

Informs the server that its credentials to access the client's system are now invalid and can no longer be used. Both parties must end any automated communication. This is the unregistration process.

Important: This method MUST return a HTTP status code 405: method not allowed if the client has not been registered before.

4. Object Description

Section 7.3

7.3.1. Credentials Object

The Credentials object describes the credentials and related information for a platform.

Property Type Cardinality Description
token string(64) 1 The credentials token for the other party to authenticate in your system. It should only contain printable non-whitespace ASCII characters, that is, characters with Unicode code points from the range of U+0021 up to and including U+007E.
url URL 1 The URL to your API versions endpoint.
hub_party_id CiString(5) ? The Hub party of this platform. The two-letter country code and three-character party ID are concatenated together in this field as one five-character string.
roles CredentialsRole + List of the roles this platform provides.
NOTE: In OCPI 2.3.0, unlike in OCPI 2.2 or 2.2.1, Roaming Hubs' platforms are expected to include the parties that are reachable through the Roaming Hub in the list in roles.

Unique Role Combinations

Every role needs a unique combination of: role, party_id and country_code. A platform can have the same role more than once, each with its own unique party_id, for example when a CPO provides 'white-label' services for 'virtual' CPOs.

Party Identification

One or more roles and thus party_id and country_code sets are provided here to inform a server about the party_id and country_code sets a client will use when pushing Client Owned Objects. This helps a server to determine the URLs a client will use when pushing a Client Owned Object. The country_code is added to make certain the URL used when pushing a Client Owned Object is unique as there might be multiple parties in the world with the same party_id. The combination of country_code and party_id should always be unique though. A party operating in multiple countries can always use the home country of the company for all connections.

EVSE IDs and Country Codes

EVSE IDs can be pushed under the country and provider identification of a company, even if the EVSEs are actually located in a different country. This way it is not necessary to establish one OCPI connection per country a company operates in. The party_id and country_code given here have no direct link with the eMI3/IDACS format EVSE IDs and Contract IDs that might be used in the different OCPI modules. A party implementing OCPI MAY push EVSE IDs with an eMI3/IDACS spot operator party_id different from the OCPI party_id and/or the country_code.

Hub Functionality

A Platform that supports Hub functionality with the Message routing headers SHALL give the country code and party ID of the Hub in the hub_party_id field.

7.3.2. Examples

Minimal CPO credentials object 
{
    "token": "ebf3b399-779f-4497-9b9d-ac6ad3cc44d2",
    "url": "https://example.com/ocpi/versions",
    "roles": [{
        "role": "CPO",
        "party_id": "EXA",
        "country_code": "NL",
        "business_details": {
            "name": "Example Operator"
        }
    }]
}
Combined CPO/eMSP credentials object 
{
    "token": "9e80a9c4-28be-11e9-b210-d663bd873d93",
    "url": "https://ocpi.example.com/versions",
    "roles": [{
        "role": "CPO",
        "party_id": "EXA",
        "country_code": "NL",
        "business_details": {
            "name": "Example Operator"
        }
    }, {
        "role": "EMSP",
        "party_id": "EXA",
        "country_code": "NL",
        "business_details": {
            "name": "Example Provider"
        }
    }]
}
CPO credentials object with full business details 
{
    "token": "9e80ae10-28be-11e9-b210-d663bd873d93",
    "url": "https://example.com/ocpi/versions",
    "roles": [{
        "role": "CPO",
        "party_id": "EXA",
        "country_code": "NL",
        "business_details": {
            "name": "Example Operator",
            "logo": {
                "url": "https://example.com/img/logo.jpg",
                "thumbnail": "https://example.com/img/logo_thumb.jpg",
                "category": "OPERATOR",
                "type": "jpeg",
                "width": 512,
                "height": 512
            },
            "website": "http://example.com"
        }
    }]
}
CPO credentials object for a platform that provides services for 3 CPOs 
{
    "token": "9e80aca8-28be-11e9-b210-d663bd873d93",
    "url": "https://ocpi.example.com/versions",
    "roles": [{
        "role": "CPO",
        "party_id": "EXO",
        "country_code": "NL",
        "business_details": {
            "name": "Excellent Operator"
        }
    }, {
        "role": "CPO",
        "party_id": "PFC",
        "country_code": "NL",
        "business_details": {
            "name": "Plug Flex Charging"
        }
    }, {
        "role": "CPO",
        "party_id": "CGP",
        "country_code": "NL",
        "business_details": {
            "name": "Charging Green Power"
        }
    }]
}

5. Data Types

Section 7.4

7.4.1. CredentialsRole class

Defines the role, party identification, and business details for a platform within the credentials exchange.

Property Type Cardinality Description
role Role 1 Type of role.
business_details BusinessDetails 1 Details of this party.
party_id CiString(3) 1 CPO, eMSP (or other role) ID of this party (following the ISO-15118 standard).
country_code CiString(2) 1 ISO-3166 alpha-2 country code of the country this party is operating in.

OCPI 2.3.0 Credentials Module — Chapter 7. Based on OCPI 2.3.0 Specification. Copyright © 2014 – 2025 EVRoaming Foundation.