API docs by Redocly

OCPI 2.3.0 - Credentials Module (2.3.0)

Download OpenAPI specification:

URL: https://evroaming.org

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.

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.

Example endpoint: /ocpi/2.3.0/credentials

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
}

Role

string <enum> (Role)
Enum Description
CPO

Charge Point Operator Role.

EMSP

eMobility Service Provider Role.

NAP

National Access Point Role (national Database with all Location information of a country).

NSP

Navigation Service Provider Role, role like an eMSP (probably only interested in Location information).

OTHER

Other role.

SCSP

Smart Charging Service Provider Role.

The role of a party in the OCPI ecosystem.

"CPO"

ImageCategory

string <open-enum> (ImageCategory)
Enum Description
CHARGER

Photo of the physical device that contains one or more EVSEs.

ENTRANCE

Location entrance photo. Should show the car entrance to the location from street side.

LOCATION

Location overview photo.

NETWORK

Logo of an associated roaming network to be displayed with the EVSE for example in lists, maps and detailed information views.

OPERATOR

Logo of the charge point operator, for example a municipality, to be displayed in the EVSEs detailed information view or in lists and maps, if no network logo is present.

OTHER

Other

OWNER

Logo of the charge point owner, for example a local store, to be displayed in the EVSEs detailed information view.

The category of an image to obtain the correct usage in a user presentation. The category has to be set accordingly to the image content in order to guarantee the right usage.

"CHARGER"

Image

url
required
string <uri>

URL from where the image data can be fetched through a web browser.

thumbnail
string <uri>

URL from where a thumbnail of the image can be fetched through a web browser.

category
required
string <open-enum> (ImageCategory)
Enum Description
CHARGER

Photo of the physical device that contains one or more EVSEs.

ENTRANCE

Location entrance photo. Should show the car entrance to the location from street side.

LOCATION

Location overview photo.

NETWORK

Logo of an associated roaming network to be displayed with the EVSE for example in lists, maps and detailed information views.

OPERATOR

Logo of the charge point operator, for example a municipality, to be displayed in the EVSEs detailed information view or in lists and maps, if no network logo is present.

OTHER

Other

OWNER

Logo of the charge point owner, for example a local store, to be displayed in the EVSEs detailed information view.

Describes what the image is used for.

type
required
string <= 4 characters

Image type like: gif, jpeg, png, svg.

width
integer

Width of the full scale image.

height
integer

Height of the full scale image.

{}

BusinessDetails

name
required
string <= 100 characters

Name of the operator.

website
string <uri>

Link to the operator's website.

object (Image)

Image link to the operator's logo.

{}

CredentialsRole

role
required
string <enum> (Role)
Enum Description
CPO

Charge Point Operator Role.

EMSP

eMobility Service Provider Role.

NAP

National Access Point Role (national Database with all Location information of a country).

NSP

Navigation Service Provider Role, role like an eMSP (probably only interested in Location information).

OTHER

Other role.

SCSP

Smart Charging Service Provider Role.

Type of role.

required
object (BusinessDetails)

Details of this party.

party_id
required
string = 3 characters

CPO, eMSP (or other role) ID of this party (following the ISO-15118 standard).

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the country this party is operating in.

{}

Credentials

token
required
string <= 64 characters

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
required
string <uri>

The URL to your API versions endpoint.

hub_party_id
string = 5 characters

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 (CiString).

required
Array of objects (CredentialsRole) non-empty

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

{}

Credentials

Get 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.

Authorizations:
ocpiAuthorization
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).

Responses

Response samples

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

Register (credentials exchange)

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.

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

Authorizations:
ocpiAuthorization
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).

Request Body schema: application/json
required

Credentials object containing the client's credentials and business details.

token
required
string <= 64 characters

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
required
string <uri>

The URL to your API versions endpoint.

hub_party_id
string = 5 characters

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 (CiString).

required
Array of objects (CredentialsRole) non-empty

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

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.

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

Authorizations:
ocpiAuthorization
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).

Request Body schema: application/json
required

Updated credentials object.

token
required
string <= 64 characters

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
required
string <uri>

The URL to your API versions endpoint.

hub_party_id
string = 5 characters

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 (CiString).

required
Array of objects (CredentialsRole) non-empty

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Unregister (invalidate 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.

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

Authorizations:
ocpiAuthorization
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).

Responses

Response samples

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