REST API Specification
for message exchange with the IPS
Revision number: 002.
© Copyright CMA Small Systems AB, 2022.
No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of CMA Small Systems AB.
This document is a work in progress. The information contained in it is subject to change or amendment with or without notice.
Revision history
|
Date |
Revision number |
Description |
|
May 18, 2022 |
002 |
Document updated. Added “Access management” and “Method “Change password”” sections. |
|
June 23, 2021 |
001 |
Document delivered |
Contents
4.3 Method "Get access token using refresh token"
6 Digital signing and verifying signatures of MX messages
1 Introduction
This document describes an application program interface (API) used for MX message exchange between Participants and IPS system.
IPS REST API (or request-based interface) allows participants to:
- Send MX messages (POST).
- Receive MX messages (GET).
- Get an access token.
- Get an access token using a refresh token.
Each participant shall implement the API on their side.
2 Sending messages
2.1 Method "Post MX message"
2.1.1 Method description
Participant application is responsible for preparing and signing the message to be sent. Once the message is prepared and signed, participant application should generate transport level request ID for this input message and send it to server using POST method of REST API.
It is recommended that you follow RFC 4122 protocol to generate the request ID.
Only one message can be sent in a single request. Multiple simultaneous sending requests are allowed.
In case of any network failure, participant application is responsible for subsequent attempts to send the message with the same request ID. Attempts must be performed until "operation successful" response (HTTP status code 200) or "bad request" response (HTTP status code 400) is received.
2.1.2 Format of service
|
Description |
Request to send MX message |
|||
|
Method |
POST |
|||
|
Client |
Participant application |
|||
|
Server |
IPS |
|||
|
URL |
||||
|
URL variables |
Variable |
Description |
||
|
request_id |
Unique reference for input message. |
|||
|
Request headers |
X-Timestamp |
Request timestamp, in ISO 8601 format. |
||
|
Content-Type |
Set this header to "application/json". |
|||
|
Accept |
Set this header to "application/json". |
|||
|
Authorization |
Contains the client token (see section 4.1 Client token ) used to authenticate a user-agent with a server. |
|||
|
Content-Length |
Size of the request body, in bytes. |
|||
|
Host |
Host address and port. |
|||
|
Request parameters |
Field |
Type |
Required |
Description |
|
traceReference |
String |
true |
Message ID generated by sender. traceReference is generated for the initial message in a message flow; all other messages in the flow must reproduce the initial traceReference. For example, when sending a pacs.008 message, the sender generates a new traceReference. When sending a pacs.002 message in response to pacs.008, the sender uses the traceReference from the original pacs.008. |
|
|
service |
String |
true |
Type of server to process the request:
|
|
|
type |
String |
true |
Message type. |
|
|
sender |
String |
true |
Sender's user code, containing 12 characters. It should a Participant user identifier (based on Participant BIC) in the method POST |
|
|
receiver |
String |
true |
Receiver's participant user code, containing 12 characters. It should a system user identifier (based on system BIC) in the method POST |
|
|
document |
String |
true |
Message text, in XML format. |
|
|
Request sample |
POST /input/0eecaf02-2301-4638-bb96-b67973c57943 HTTP/1.1 X-Timestamp: 2018-08-13T12:15:54.651Z Content-Type: application/json Accept: application/json Authorization: Bearer eyJ...iJ9.eyJ...jJ9.Ac-...0MSw Content-Length: 5634 Host: asrv:23432 { "traceReference": "CKvOI85gv0SgNKqLAxBpwQ", "service": "M", "type": "pacs.008.001.08", "sender": "PARTIBICXUSR", "receiver": " SYSTEBICXUSR ", "document": "<DataPDU ...>...</DataPDU>" }
|
|||
|
Response headers |
Content-Type |
Media type of the response. |
||
|
X-Request-ID |
{request_id} identical to the request above. Can be used to link request and response together. |
|||
|
X-Timestamp |
Response timestamp, in ISO 8601 format. |
|||
|
Server-Timing |
Detailed statistics of server time spent to process the request and prepare the response. |
|||
|
|
Response may also contain a set of technical and security headers generated automatically (see sample below). These headers are not listed here. |
|||
|
Successful response sample |
HTTP/1.1 200 OK X-Request-ID: 0eecaf02-2301-4638-bb96-b67973c57943 X-Timestamp: 2018-08-13T12:15:54.651Z X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 Strict-Transport-Security: max-age=31536000 ; includeSubDomains X-Frame-Options: DENY Server-Timing: acc;dur=123, app;dur=120 |
|||
|
Error response sample |
HTTP/1.1 401 Unauthorized X-Request-ID: 0eecaf02-2301-4638-bb96-b67973c57943 X-Timestamp: 2018-08-13T12:15:54.651Z X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 Strict-Transport-Security: max-age=31536000 ; includeSubDomains X-Frame-Options: DENY Server-Timing: acc;dur=123, app;dur=120 { "timestamp": "2019-10-14T10:14:41.305+0000", "status": 500, "errorCode": "GE" "error": "Internal Server Error", "message": "No space left on device", " path ": "/ input " } |
|||
|
HTTP response codes |
200 |
Successful operation |
||
|
400 |
Bad request |
|||
|
401 |
Unauthorized |
|||
|
Error response parameters |
Field |
Type |
Required |
Description |
|
timestamp |
String |
true |
Response timestamp. |
|
|
status |
String |
true |
HTTP response status code. |
|
|
errorCode |
String |
true |
Error code. |
|
|
error |
String |
true |
Error name. |
|
|
message |
String |
true |
Message describing the response. |
|
|
path |
String |
true |
URL path. |
|
3 Receiving messages
3.1 Method "Get MX message"
3.1.1 Method description
Participant application is responsible for generating a request ID. GET output message request should be repeated instantly in separate thread to receive all output messages.
It is recommended to follow RFC 4122 protocol to generate the request ID.
Multiple messages can be received in a single response.
In case of any network failure, participant application is responsible for subsequent attempts to receive a new output message with same request ID. Attempts must be performed until "operation successful" response (HTTP status code 200) or "bad request" response (HTTP status code 400) is received.
- Participant can open a thread and make a GET API call with a specific timeout value (long pooling request, recommended 10 seconds, X-Fetch-Timeout)
- If any message is received on thread it will be received by participant and processed.
- Participant should not initiate new GET request (request with new “request_id”) inside a thread until response on the previous one is not received
Note that participant application can receive messages is a single thread or in parallel threads. In the latter case, the participant application is responsible for the correct processing of messages out of chronological order (for example, due to parallelism, a payment status message might arrive earlier than the related payment message).
3.1.2 Format of service
|
Description |
Request to receive message |
||||
|
Method |
GET |
||||
|
Client |
Participant application |
||||
|
Server |
IPS |
||||
|
URL |
|||||
|
URL variables |
Variable |
Description |
|||
|
request_id |
Unique reference for output message. |
||||
|
Request headers |
Accept |
Set this header to "application/json". |
|||
|
Request timeout period, in ms. If no response is received immediately, sender will wait for the response until this period expires. |
|||||
|
X-Fetch-Size |
Maximum number of messages allowed per response. This is a system parameter that can be modified by the operator. Maximum value is 10. |
||||
|
X-Timestamp |
Request timestamp, in ISO 8601 format. |
||||
|
Authorization |
Contains the client token (see section 4.1 Client token ) used to authenticate a user-agent with a server. |
||||
|
Host |
Host address and port. |
||||
|
Request sample |
GET /output/0eecaf02-2301-4638-bb96-b67973c57943 HTTP/1.1 Accept: application/json X-Fetch-Timeout: 15000 X-Fetch-Size: 5 X-Timestamp: 2018-08-13T12:15:54.651Z Authorization: Bearer eyJ...iJ9.eyJ...jJ9.Ac-...0MSw Host: asrv:23432 |
||||
|
Response headers |
Content-Type |
Media type of the response. |
|||
|
Content-Length |
Total length of messages in response, in bytes. |
||||
|
X-Request-ID |
Must be {request_id} identical to the request above. |
||||
|
X-Timestamp |
Response timestamp, in ISO 8601 format. |
||||
|
X-Fetch-Count |
Number of messages in the response. |
||||
|
Server-Timing |
Detailed statistics of server time spent to process the request and prepare the response. |
||||
|
|
Response may also contain a set of technical and security headers generated automatically (see sample below). These headers are not listed here. |
||||
|
Successful response sample |
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 4237 X-Request-ID: 0eecaf02-2301-4638-bb96-b67973c57943 X-Timestamp: 2018-08-13T12:15:54.651Z X-Fetch-Count: 2 X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 Strict-Transport-Security: max-age=31536000 ; includeSubDomains X-Frame-Options: DENY Server-Timing: acc;dur=123,app;dur=120,wait;dur=100,queue;dur=0 [ { "traceReference": "CKvOI85gv0SgNKqLAxBpwQ.0", "type": "pacs.002.001.09", "sender": " SYSTEBICXUSR", "receiver": "PARTIBICXUSR", "document": "<DataPDU ...>...</DataPDU>" }, { "traceReference": "IgULMaA3a0W4bksqhIrQLg.0", "type": "pacs.002.001.09", "sender": " SYSTEBICXUSR ", "receiver": " PARTIBICXUSR ", "document": "<DataPDU ...>...</DataPDU>" } ]
|
||||
|
Error response sample |
HTTP/1.1 401 Unauthorized Content-Type: application/json Content-Length: 4237 X-Request-ID: 0eecaf02-2301-4638-bb96-b67973c57943 X-Timestamp: 2018-08-13T12:15:54.651Z X-Fetch-Count: 2 X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 Strict-Transport-Security: max-age=31536000 ; includeSubDomains X-Frame-Options: DENY Server-Timing: acc;dur=123,app;dur=120,wait;dur=100,queue;dur=0 { "timestamp": "2019-10-14T10:14:41.305+0000", "status": 500, "errorCode": "GE" "error": "Internal Server Error", "message": "No space left on device", " path ": "/ output " }
|
||||
|
HTTP response codes |
200 |
Successful operation |
|||
|
204 |
No new messages to process |
||||
|
400 |
Bad request |
||||
|
401 |
Unauthorized |
||||
|
Success response parameters |
Field |
Type |
Required |
Description |
|
|
traceReference |
String |
true |
Message ID generated by sender. traceReference is generated for the initial message in a message flow; all other messages in the flow must reproduce the initial traceReference. |
||
|
type |
String |
true |
Message type. |
||
|
sender |
String |
true |
Sender's participant user code, containing 12 characters. It should a system user identifier (based on system BIC) in the method GET |
||
|
receiver |
String |
true |
Receiver's participant user code, containing 12 characters. It should a Participant user identifier (based on Participant BIC) in the method GET |
||
|
document |
String |
true |
Message text, in XML format. |
||
|
Error response parameters |
Field |
Type |
Required |
Description |
|
|
timestamp |
String |
true |
Response timestamp. |
||
|
status |
String |
true |
HTTP response status code. |
||
|
errorCode |
String |
true |
Error code. |
||
|
error |
String |
true |
Error name. |
||
|
message |
String |
true |
Message describing the error. |
||
|
path |
String |
true |
URL path. |
||
4 Authentication
To be able to exchange messages with IPS, Client must pass token-based authentication.
To do this, Client needs to:
- Generate a client token.
For details, see section 4.1 Client token .
- Get an access token and refresh token from access server.
For details, see sections 4.2 Method "Get access token" and 4.3 Method "Get access token using refresh token" .
Once these steps are successfully completed, Client is considered to be authenticated with IPS and can send and receive messages.
4.1 Client token
Client token is used for access token generation requests. When REST signatures are enabled for Client, token signature is verified by a certificate with the asrv_cert_sn serial number issued by asrv_cert_issuer.
Client generates a client token in JWT format, as described below.
Client token payload example:
|
{ "iss": "TMSXSHR0AXXX", "iat": 1565601704, "exp": 4687665704, "asrv_type": "client", "asrv_cert_iss": "cn=access-server-test,o=cma,c=ru", "asrv_cert_sn": "5D 4D 8E C1" } |
Client token JWT claims:
|
Claim |
Description |
|
iss |
Client (participant) user code (e.g., PARTIBICXUSR) . |
|
iat |
The "issued at" claim identifies the time at which the JWT was issued (seconds from 1970-01-01T00:00:00Z UTC). |
|
exp |
The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing (seconds from 1970-01-01T00:00:00Z UTC). |
|
asrv_type |
Token type, should be client. |
|
asrv_cert_iss |
Client certificate issuer. |
4.2 Method "Get access token"
4.2.1 Method description
To obtain an access token for authentication, Client sends an access token request. In response, Access server performs password-based authentication and issues an access token with short lifetime and refresh token with long lifetime.
Refresh token is used to obtain additional access tokens on demand without sending user’s password.
If Client request does not contain the Authorization header or if it contains an invalid token, the response will receive error 401.
4.2.2 Format of service
|
Description |
Request to get an access token |
|||
|
Method |
POST |
|||
|
Client |
Participant application |
|||
|
Server |
Access server |
|||
|
URL |
https://<access-server-host:access-server-port>/token |
|||
|
Request variables |
Variable |
Description |
||
|
grant_type |
Authentication type. Set this parameter to "password". |
|||
|
username |
Username for authentication. |
|||
|
password |
Password for authentication. |
|||
|
Request headers |
Content-Type |
Set this header to "application/x-www-form-urlencoded". |
||
|
Accept |
Set this header to "application/json". |
|||
|
Content-Length |
Length of request body, in bytes. |
|||
|
Authorization |
Contains the client token (see section 4.1 Client token ) used to authenticate a user-agent with a server. |
|||
|
Host |
Host address and port. |
|||
|
Request sample |
POST /token HTTP/1.1 Content-Length: 52 Accept: application/json Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhc3J2X2NlcnRfc24iOiI1RCA0RCA4RSBDMSIsImlzcyI6IlRNU1hTSFIwQVhYWCIsImFzcnZfdHlwZSI6ImNsaWVudCIsImV4cCI6NDY4NzY2NTcwNCwiYXNydl9jZXJ0X2lzcyI6ImNuPWFjY2Vzcy1zZXJ2ZXItdGVzdCxvPWNtYSxjPXJ1IiwiaWF0IjoxNTY1NjAxNzA0fQ.QEoH5q6sDoidY2yFj6IcknZZyb1l-6dfACTT2-za210C1K-UrCXN73YM7NcfGg9lByRbcCD-avgKWQ5FiPGpYBDvGdZUVqNYb1YrB0BwB1--Ej2WdOe9emehQ8yFwXX3peoVk0J24mL2foqR4Ras_IDbcFb6uxd6Ph_FZP3Jc2O8i30HFxi_tTClbr9pqnzBPlpP9qEQxYESmaSLAEjdek3-AzuhOxN_WZvRJqdlIsgYx0vtfBzoER39Th-Esx_LIxnkVwXK2DnxzNIfrUF8xdZdrW1E9F7x40LjR83QnVod4JCJuAOUWEYlxe2sqH7d7Ap5ciE6g1zbI79o6mvoHQ Content-Type: application/x-www-form-urlencoded Host: asrv:23432 grant_type=password&username=PARTIBICXUSR&password= qwerty
|
|||
|
Response headers |
Content-Length |
Size of the response body, in bytes. |
||
|
|
Response may also contain a set of technical and security headers generated automatically (see sample below). These headers are not listed here. |
|||
|
Successful response sample |
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Content-Length: 1280 Expires: 0 X-Frame-Options: DENY X-Content-Type-Options: nosniff Content-Type: application/json;charset=UTF-8 Strict-Transport-Security: max-age=31536000 ; includeSubDomains Cache-Control: no-cache, no-store, max-age=0, must-revalidate
{ "access_token" : "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJUTVNYU0hSMEFYWFgiLCJ4NXQiOiJaY194NHBJSFgyemEyeTdNaUlQVUJhNHFCOXMiLCJhc3J2X3R5cGUiOiJhY2Nlc3MiLCJleHAiOjE1ODE2MzQwNzYsImlhdCI6MTU4MTYzMDQ3Nn0.TdvkC71PIgGvpG8cDCiW26fK00L-Wc5UPxtfF9GF4jXMz4jsnWNPEAXaqf6DPWS8AEtCWPvo-jwSuOUXT5LAMXb0a1vZQiKzgQh5n9dM4qVwnORtfHvDubGdpqWqc6WAin7FREGCr275EVQS64AO37Bjjtj7ibRWvoyYbTCBbe6rLXtMMPvzN1-NvIAC0vRO2AlNecpDBrSXKp29xIDL_EZnNS-uLegOGimDXIptOlCDyBlHAOs8wotD_e5FFiEnWDOxmGq0jv4OzmoNX8qady8Fvor0OG4QOYKEQoWopl-AlHoxX7BkHgj20L_yVGkCeUe-nY65lchifwYNj83xIA", "token_type" : "bearer", "expires_in" : 3600, "refresh_token" : "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJUTVNYU0hSMEFYWFgiLCJ4NXQiOiJaY194NHBJSFgyemEyeTdNaUlQVUJhNHFCOXMiLCJhc3J2X3R5cGUiOiJyZWZyZXNoIiwiZXhwIjoxNTgxNzE2ODc2LCJpYXQiOjE1ODE2MzA0NzZ9.LjnUhVvAT__ybkt5BQkpaOBnizLvov4y4PC84Hy9ePWZk0qc4sXCoWr8iA1sIr1imIYEqn46osSfg_TmYYWOiUm-H4sTMDa0VqSVG7D5YK62eHBk_knLHumUopK54ow3tMYDydlqK4o6Pm5vyiCpj0DO81ea0oajiP7fePt9ESzjZGzCrZ3qKmcR6J0WgdnyGGIn88jsvXxfjekpjvClMpVUDAUJWo3WpSs_sO0EAWrIWwBWg1dnlHjBIOGKxRdAvmyuKBemuLxmFTxW8DfsNLglEF2VO4-JEAgbHSWV9F67Pk-pJ8g9AF4TTipsDffpRNvcCVE5nNxS9OjG1Midtw", "refresh_expires_in" : 86400 }
|
|||
|
Error response sample |
HTTP/1.1 401 Unauthorized Pragma: no-cache X-XSS-Protection: 1; mode=block Content-Length: 92 Expires: 0 X-Frame-Options: DENY X-Content-Type-Options: nosniff Content-Type: application/json;charset=UTF-8 Strict-Transport-Security: max-age=31536000 ; includeSubDomains Cache-Control: no-cache, no-store, max-age=0, must-revalidate WWW-Authenticate: Bearer realm="access_server" { "error" : "invalid_client", "error_description" : "Wrong user PARTIBICXUSR password" }
|
|||
|
HTTP response codes |
200 |
Successful operation |
||
|
400 |
Bad request |
|||
|
401 |
Unauthorized |
|||
|
420 |
User must change password |
|||
|
Success response parameters |
Field |
Type |
Required |
Description |
|
access_token |
String |
true |
Access token issued by the access server. |
|
|
token_type |
String |
true |
Type of the issued tokens. Must be “bearer”. |
|
|
expires_in |
String |
true |
Lifetime of the access token, in seconds. |
|
|
refresh_token |
String |
true |
Refresh token issued by the access server. |
|
|
refresh_expires_in |
String |
true |
Lifetime of the refresh token, in seconds. |
|
|
Error response parameters |
Field |
Type |
Required |
Description |
|
error |
String |
true |
Error name. |
|
|
error_description |
String |
true |
Message describing the error. |
|
4.3 Method "Get access token using refresh token"
4.3.1 Method description
Client can send request to Access server for a new access token based on a previously issued and valid refresh token without specifying user's password.
If Client request does not contain the Authorization header or if it contains an invalid token, the response will receive error 401.
4.3.2 Format of service
|
Description |
Request to get an access token using refresh token |
|||
|
Method |
POST |
|||
|
Client |
Participant application |
|||
|
Server |
Access server |
|||
|
URL |
https://<access-server-host:access-server-port>/token |
|||
|
Request variables |
Variable |
Description |
||
|
grant_type |
Authentication type. Set this parameter to "refresh_token". |
|||
|
refresh_token |
Refresh token that was issued previously. |
|||
|
Request headers |
Content-Type |
Set this header to "application/json". |
||
|
Accept |
Set this header to "application/x-www-form-urlencoded". |
|||
|
Content-Length |
Size of the request body, in bytes. |
|||
|
Authorization |
Contains the client token (see section 4.1 Client token ) used to authenticate a user-agent with a server. |
|||
|
Host |
Host address and port. |
|||
|
Request sample |
HTTP request POST /token HTTP/1.1 Accept: application/json Content-Length: 614 Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhc3J2X2NlcnRfc24iOiI1RCA0RCA4RSBDMSIsImlzcyI6IlRNU1hTSFIwQVhYWCIsImFzcnZfdHlwZSI6ImNsaWVudCIsImV4cCI6NDY4NzY2NTcwNCwiYXNydl9jZXJ0X2lzcyI6ImNuPWFjY2Vzcy1zZXJ2ZXItdGVzdCxvPWNtYSxjPXJ1IiwiaWF0IjoxNTY1NjAxNzA0fQ.QEoH5q6sDoidY2yFj6IcknZZyb1l-6dfACTT2-za210C1K-UrCXN73YM7NcfGg9lByRbcCD-avgKWQ5FiPGpYBDvGdZUVqNYb1YrB0BwB1--Ej2WdOe9emehQ8yFwXX3peoVk0J24mL2foqR4Ras_IDbcFb6uxd6Ph_FZP3Jc2O8i30HFxi_tTClbr9pqnzBPlpP9qEQxYESmaSLAEjdek3-AzuhOxN_WZvRJqdlIsgYx0vtfBzoER39Th-Esx_LIxnkVwXK2DnxzNIfrUF8xdZdrW1E9F7x40LjR83QnVod4JCJuAOUWEYlxe2sqH7d7Ap5ciE6g1zbI79o6mvoHQ Content-Type: application/x-www-form-urlencoded Host: asrv:23432
grant_type=refresh_token&refresh_token= eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJUTVNYU0hSMEFYWFgiLCJ4NXQiOiJaY194NHBJSFgyemEyeTdNaUlQVUJhNHFCOXMiLCJhc3J2X3R5cGUiOiJyZWZyZXNoIiwiZXhwIjo0Njg3NjY4ODYzLCJpYXQiOjE1NjU2MDQ4NjN9.Cz_Gjqjk3x0JFC9BEKrrj6D0eQLmmy9yKDyk_DSSKZIv0jZiHSXy3LN-yWWIdP1V3xrxkeuok257z3rY3xAka5JMzpKvjE9KAWJrE-dW5wMzfIB-Pyy85rOnD89Oa46gCJPp8O6O_9jRXKho6FTF6Bui_mSLCH6oG4K6CNgJftIBPY-_cTKP1ow8FcuWFWhDPJskrkXGXDe4Md36WeSAjlFdLWEazPjdtaZcFvECZEchAiYE-XuC5QmUK7TIzTvfJDQc6rILWKgALLr9QL-gZzgqxWHQysnVryPW-cVwXdlrP5fJbo46fG_3HDs8Sm2bZoZfEaom0k4pLGFuph0Xkw
|
|||
|
Response headers |
Content-Length |
Size of the response body, in bytes. |
||
|
|
Response may also contain a set of technical and security headers generated automatically (see sample below). These headers are not listed here. |
|||
|
Successful response sample |
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Content-Length: 1280 Expires: 0 X-Frame-Options: DENY X-Content-Type-Options: nosniff Content-Type: application/json;charset=UTF-8 Strict-Transport-Security: max-age=31536000 ; includeSubDomains Cache-Control: no-cache, no-store, max-age=0, must-revalidate
{ "access_token" : "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJUTVNYU0hSMEFYWFgiLCJ4NXQiOiJaY194NHBJSFgyemEyeTdNaUlQVUJhNHFCOXMiLCJhc3J2X3R5cGUiOiJhY2Nlc3MiLCJleHAiOjE1ODE2MzQwNzYsImlhdCI6MTU4MTYzMDQ3Nn0.TdvkC71PIgGvpG8cDCiW26fK00L-Wc5UPxtfF9GF4jXMz4jsnWNPEAXaqf6DPWS8AEtCWPvo-jwSuOUXT5LAMXb0a1vZQiKzgQh5n9dM4qVwnORtfHvDubGdpqWqc6WAin7FREGCr275EVQS64AO37Bjjtj7ibRWvoyYbTCBbe6rLXtMMPvzN1-NvIAC0vRO2AlNecpDBrSXKp29xIDL_EZnNS-uLegOGimDXIptOlCDyBlHAOs8wotD_e5FFiEnWDOxmGq0jv4OzmoNX8qady8Fvor0OG4QOYKEQoWopl-AlHoxX7BkHgj20L_yVGkCeUe-nY65lchifwYNj83xIA", "token_type" : "bearer", "expires_in" : 3600, }
|
|||
|
Error response sample |
HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="access_server" X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 Strict-Transport-Security: max-age=31536000 ; includeSubDomains X-Frame-Options: DENY Content-Length: 104 { "error" : "invalid_client", "error_description" : "client token has wrong certificate signature" }
|
|||
|
HTTP response codes |
200 |
Successful operation |
||
|
400 |
Bad request |
|||
|
401 |
Unauthorized |
|||
|
Success response parameters |
Field |
Type |
Required |
Description |
|
access_token |
String |
true |
Access token issued by the access server. |
|
|
token_type |
String |
true |
Type of the issued tokens. Must be “bearer”. |
|
|
expires_in |
String |
true |
Lifetime of the access token, in seconds. |
|
|
Error response parameters |
Field |
Type |
Required |
Description |
|
error |
String |
true |
Error name. |
|
|
error_description |
String |
true |
Message describing the error. |
|
5 Access Management
5.1 Method "Change password"
5.1.1 Method description
This request is used to change a user password.
The authentication is performed by using client token (see section 4.1 Client token ). The token signature is verified only when transport signatures are enabled for the user.
The current password and the new password are sent in the current_pwd and new_pwd parameters of the request.
5.1.2 Format of service
|
Description |
Request to change password |
|||
|
Method |
POST |
|||
|
Client |
Participant application |
|||
|
Server |
Access server |
|||
|
URL |
https://<access-server-host:access-server-port>/change-password |
|||
|
Request variables |
Variable |
Description |
||
|
new_pwd |
New password. |
|||
|
current_pwd |
Current password. |
|||
|
Request headers |
Content-Type |
Set this header to “application/x-www-form-urlencoded”. |
||
|
Accept |
Set this header to "application/json". |
|||
|
Content-Length |
Length of request body, in bytes. |
|||
|
Authorization |
Contains the client token (see section 4.1 Client token ) used to authenticate a user-agent with a server. |
|||
|
Host |
Host address and port. |
|||
|
Request sample |
POST /change-password HTTP/1.1 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Accept: application/json Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhc3J2X2NlcnRfc24iOiI1RCA0RCA4RSBDMSIsImlzcyI6IkNCT01PTVJVV1JQRyIsImFzcnZfdHlwZSI6ImNsaWVudCIsImV4cCI6NzAzOTIwMjUwNiwiYXNydl9jZXJ0X2lzcyI6ImNuPWFjY2Vzcy1zZXJ2ZXItdGVzdCxvPWNtYSxjPXJ1IiwiaWF0IjoxNjE4ODU4NTA2fQ.TBUwFDraVze8qzq129OOi1s-aB7hlcZpUfehhsnVXMTzzacNh-aTW-YrvVV0ZQVPhDRimZL98vdkC1OrhYFrTSfCUjxWo7ljhyJxAFbLa_NBtZVKKW99dvx50ENiWV38IJmDCa7q7RUvNI7QO6vsyen3p2lnbSssQYGOmpds3_TTpp06DqlW1fKpwWTTs6xGhZ7NV-NdyWlCBTLYY1wUAaOy_cOio5LIuBndFJNEfS9EGB4WlxHbNaexRdBSumBAwS2NcomRO8gZy1tstuYMLxo6Yqkeq3nmfd8SI-6ynCPDQGxfvqr-11mS39w7b0EC6M6KueQYA0VfzJKtSmVAxw Content-Length: 28 Host: asrv:23432
new_pwd=123456¤t_pwd=1 |
|||
|
Response headers |
Content-Type |
Media type of the response. |
||
|
Content-Length |
Total length of messages in response, in bytes. |
|||
|
|
Response may also contain a set of technical and security headers generated automatically (see sample below). These headers are not listed here. |
|||
|
Successful response sample |
HTTP/1.1 200 OK X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 Strict-Transport-Security: max-age=31536000 ; includeSubDomains X-Frame-Options: DENY |
|||
|
Error response sample |
HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8 Content-Length: 67 X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 Strict-Transport-Security: max-age=31536000 ; includeSubDomains X-Frame-Options: DENY
{ "error" : "EP174", "error_description" : "Invalid password" } |
|||
|
HTTP response codes |
200 |
Successful operation |
||
|
400 |
Bad request |
|||
|
401 |
Unauthorized |
|||
|
Error response parameters |
Field |
Type |
Required |
Description |
|
error |
String |
true |
Error name. |
|
|
error_description |
String |
true |
Message describing the error. |
|
6 Digital signing and verifying signatures of MX messages
For detailed information on signing and verifying signatures of MX messages, see document "MX Messages signing guide".