--- title: "Update the authentication" method: POST path: "/updateAuthentication" tags: ["authentication"] --- # Update the authentication `POST /updateAuthentication` ## Request - Base URL: `https://financial-services.developer.worldline.com` (the document declares no server; this is the origin it was published from) - URL: `https://financial-services.developer.worldline.com/updateAuthentication` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) This method is used by the APM to forward the device chosen by the cardholder to the bank, in case the bank returned a list of devices during the initiateAuthentication call. ## Headers - `Authorization` string - `Date` string, rfc5322 - `Digest` string - `Signature` string - `x-jws-signature` string ## Request body - UpdateRequestMessage: Update authentication request. - `header` Header, required: Metadata of the message. - `service` string, required: Service code of the caller, defined during project. - `issuerCode` string, required: Unique identifier code of issuer. - `subIssuerCode` string, required: Unique identifier code of sub-issuer. - `requestId` string, uuid, required: Unique identifier of the request. - `keyTag` string: Key indicator shared between client and server. - `iv` string: IV value used to crypt data. Can either be the requestId without dashes, a random value, or equals to the null IV. 32 characters long in case of CBC mode, 24 characters long in case of GCM mode (expect if configured otherwise). - `body` UpdateRequest, required: Update authentication request payload. - `principal` Principal, required: A pair of a type and a value (potentially encrypted). - `type` string, required: The type. - `value` string, required: The value. - `expiry` Expiry: A pair of a type and a value (potentially encrypted). - `type` string, required: The type. - `value` string, required: The value. - `sessionId` string, uuid, required: The unique identifier of the authentication session. - `transactionId` string: The bank's unique identifier of the authentication transaction. - `chosenDevice` Device: The device information. - `id` string: The device identifier. - `value` string: The device value. - `freeContext` FreeContext: A free map to add any specific information. - `signature` string: The signature of the message. The signature is optional and is only filled and/or checked if explicitly required. Otherwise, signature value is ignored in responses and left empty in requests. Signatures can be activated for each issuer, sub-issuer individually and at a method level. To pass validation, the signature format must be RFC 7515 (JSON Web Signature) and RFC 7797 (Unencoded or detached payload) compliant. As such, a typical signature should look like this: `[header]..[signature]`, where: - `[header]` is the Base64 URL encoded value of the JOSE header which contains the key ID, algorithm and object type. For example: `eyJraWQiOiJzaWduIiwidHlwIjoiSk9TRStKU09OIiwiYWxnIjoiUlMyNTYifQ`, which gives, in clear JSON: `{"kid":"sign","typ":"JOSE+JSON","alg":"RS256"}`. The `kid` (Key ID) and `alg` header fields are both required to perform the check. An additional `jku` parameter (JWKS URL where to retrieve the public key) can also be specified. Otherwise, it should be expected for public keys to have been exchanged beforehand. The `typ` is only there by convention and should only be set to `JOSE` or `JOSE+JSON` since were are not dealing JWT (tokens) here. - `[signature]` is the Base64 URL encoded value representation of the signature output. The payload used to generate the signature consists of the JSON serialization of the whole object, excluding old signatures and null values, which is then Base 64 URL encoded as well. If the signature from the response contains a payload value, then it will be ignored in favor of the actual object. Currently supported algorithms are: - RS256 - RS384 - RS512 - ES256 - ES256K - ES384 - ES512 ## Response `200` Update response. - UpdateResponseMessage: Updated authentication response. - `header` Header, required: Metadata of the message. - `service` string, required: Service code of the caller, defined during project. - `issuerCode` string, required: Unique identifier code of issuer. - `subIssuerCode` string, required: Unique identifier code of sub-issuer. - `requestId` string, uuid, required: Unique identifier of the request. - `keyTag` string: Key indicator shared between client and server. - `iv` string: IV value used to crypt data. Can either be the requestId without dashes, a random value, or equals to the null IV. 32 characters long in case of CBC mode, 24 characters long in case of GCM mode (expect if configured otherwise). - `body` UpdateResponse, required: Update authentication response payload. - `result` Result: The result of the authentication. - `resultCode` 'SUCCESS' | 'FAILURE', required: Is the authentication successful. - `trialLeft` integer: The number of trials left to try again. - `freeContext` FreeContext: A free map to add any specific information. - `signature` string: The signature of the message. The signature is optional and is only filled and/or checked if explicitly required. Otherwise, signature value is ignored in responses and left empty in requests. Signatures can be activated for each issuer, sub-issuer individually and at a method level. To pass validation, the signature format must be RFC 7515 (JSON Web Signature) and RFC 7797 (Unencoded or detached payload) compliant. As such, a typical signature should look like this: `[header]..[signature]`, where: - `[header]` is the Base64 URL encoded value of the JOSE header which contains the key ID, algorithm and object type. For example: `eyJraWQiOiJzaWduIiwidHlwIjoiSk9TRStKU09OIiwiYWxnIjoiUlMyNTYifQ`, which gives, in clear JSON: `{"kid":"sign","typ":"JOSE+JSON","alg":"RS256"}`. The `kid` (Key ID) and `alg` header fields are both required to perform the check. An additional `jku` parameter (JWKS URL where to retrieve the public key) can also be specified. Otherwise, it should be expected for public keys to have been exchanged beforehand. The `typ` is only there by convention and should only be set to `JOSE` or `JOSE+JSON` since were are not dealing JWT (tokens) here. - `[signature]` is the Base64 URL encoded value representation of the signature output. The payload used to generate the signature consists of the JSON serialization of the whole object, excluding old signatures and null values, which is then Base 64 URL encoded as well. If the signature from the response contains a payload value, then it will be ignored in favor of the actual object. Currently supported algorithms are: - RS256 - RS384 - RS512 - ES256 - ES256K - ES384 - ES512 ## Other responses - `default`: Error response. --- [API](https://skmtc.dev/worldline/apis/authentication-ws-client.md) - [All operations](https://skmtc.dev/worldline/apis/authentication-ws-client/llms.txt) - [OpenAPI document](https://skmtc.dev/worldline/apis/authentication-ws-client/revisions/5c21f3ad0e19?raw)