API Concepts

Servers

Env	Url	Description
PROD	https://idp.peax.ch/auth/realms/peax-id-prod/protocol/openid-connect/token	IDP - Authentication Server
PROD	https://proxy.peax.ch	API Endpoints
STAGE	https://idp-stage.peax.ch/auth/realms/peax-id-stage/protocol/openid-connect/token	IDP - Authentication Server
STAGE	https://proxy-stage.peax.ch	API Endpoints

The stage environment is operational between 04:00 - 22:00 on weekdays.

Version management

The API may change over time. The semantic versioning is being used in the API, but only major changes are relevant (not backward-compatible changes).

https://api.peax.ch/.../v1/...

Authentication

To use the API, the client should have to authenticate itself by using oauth2 with the client credential flow:

curl --location --request POST '{IDP_URL}/auth/realms/peax-id-prod/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cache-Control: no-cache' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_secret={client_secret}' \
--data-urlencode 'client_id={client_id}'

The client_id and client_secret will be provided by PEAX for the production and stage environments.

Response

The above call produces a response with tokens (JWT). The “access_token“ is to be used in all subsequent API calls in the request header “Authorization“ (as Bearer Token).

{
    "access_token": "eyJh...",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJh...",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "b11eb21c-1a08-4488-ab4d-6dba81b2c11e",
    "scope": "profile email"
}

Pagination

Our APIs support pagination to ensure efficient data retrieval and to provide a manageable experience when working with large datasets. Here's how you can utilize it:

Pagination splits a large dataset into smaller chunks or "pages". Instead of returning all records in one response, only a subset is sent, depending on the specified page and page size.

Usage

Query Parameters:

page: Specifies the current page number. Defaults to 0 if not provided.

size: Specifies the number of records per page. Defaults to 20 if not provided.

Requesting /documents?page=2&size=15 will retrieve records 16-30.

Response Structure: Alongside the data, the response will provide pagination metadata:

pageNo: The page number of the current set.

pageSize: The number of records in the current page.

totalCount: The total number of available records.

totalPages: The total number of pages available.

Optional links for navigation to the next and previous pages might also be included.

Error Handling

The Partner API has global exception handling. In case of any error, the client gets the following payload in the response along with the appropriate HTTP status. This object has an error code and text for the error description.

The payload format is defined in open-API as well.

{
  "code": "400",
  "messageKey": "InvalidRequest",
  "info": [
    {
      "name": "timestamp",
      "value": "2024-02-28T12:34:56Z"
    },
    {
      "name": "requestId",
      "value": "abc123"
    }
  ],
  "errors": [
    {
      "fieldName": "email",
      "validationMessage": "Email format is invalid."
    },
    {
      "fieldName": "password",
      "validationMessage": "Password must be at least 8 characters long."
    }
  ]
}

Error Codes

Code	Name	Cause
400	Bad request	Request bad formatted Media type not supported Missing parameter in request
401	Unauthorized	Access token expired or no access token
403	Forbidden	Not authorized
404	Not Found	No resource found
409	Conflict	Business validation error
410	Gone	Resource is not existing any more.
500	Internal server error	Unexpected error at server site

Character Set

The charset of HTTP requests and responses is default UTF-8. If it is not defined in the request on header "Content-Type", it is added automatically.

General

API Concepts#

Servers#

Version management#

Authentication#

Response#

Pagination#

Error Handling#

Error Codes#

Character Set#

API Concepts

Servers

Version management

Authentication

Response

Pagination

Error Handling

Error Codes

Character Set