End to end encryption of sensitive data like passwords and one time pins is a security mandate in some countries. The /security resource allows you to exchange keys which are used for encryption and decryption. Key exchange methods differ depending on whether you already have a registered key or whether you need Citi to send you a key which can be used for encryption. You will receive eventID in the API response header, which should be used to encrypt the sensitive data. All encrypted data sent to Citi will give you an additional eventID in response header, this new eventID should be used for further encryptions.
Paths
/v1/security/e2eKey
Used by Mobile App(Native) to Save the session level key for native applications.
This API is used by Native applications for setting the session level key. The Key is generated on the device and transferred to this API. This key is encrypted with the Public key embedded inside the application. This API returns the encrypted eventID and expiration time in the header.
Follow the below steps to encrypt the key.
1.Generate IV – convert to HEX 32 CHAR (This is so that server can encrypt the ServerRandom with this)
2.Generate 256 bit AES key and convert to HEX
3.Generate check digit – CD
4.Encrypt AES key with RSA public key as – RSA(AES)
5.Frame the payload as – CD, IV(RSA[AES])
ClientID
ClientID
The client ID you received during application registration in the developer portal
{
"default": "29738e5a-fbbf-4b55-981d-d2f3d2a60605"
}The most recent Authorization token
{
"default": "Y2wwIEhvzLEVhkiGkF3hAAYhePuCT39lSyTz41+4JIXoxevJOQSwVanbHgDAeah+Xwqr5DO3b1f+YQIZ0ZCjitOMz3fmtXOO9QTwxUDoxMNTGYWuQVnq1ElO1qStxFGg0nHEgwPhfykc3g4cF\/HmGksD73Naefo+xl6OPTDRCsQTz3\/GS4sT5QA7U\/QSDlGSWaRlyr5BBg9+YppAh+jQmKn2R3xd3Huhngp0M4kRx7zX28CziSBymBhjqnaXXFDuCu3pSFMl5bL+Peo9awnjx6tSDyohqDZj4tWDUfp4r3o="
}HTTP Accept-Language header
{
"default": "en-US"
}Content-Types that are acceptable for the response. Currently we support application/json
{
"default": "application\/json"
}A 128 bit universally unique identifier (UUID) that you generate for every request and is used for tracking. It is recommended to use the output from Java UUID class or an equivalent.
{
"default": "a7d1e304-83a9-4413-af97-62615e57eae66807840"
}application/json
{
"default": "application\/json"
}Request object with encrypted symmetric key to store. For now, we are allowing only AES as the algorithm of the symmetric key.
Successfully stored Symmetric key and returned the encrypted event ID and expiration time in header.
(BAD REQUEST) - Request was not processed
| Type | Code | Details |
| invalid | invalidRequest | Missing or invalid Parameters |
| error | chkDigitNotMatch | Check digits do not match |
| error | cannotDecryptKey | Key not properly encrypted. please recheck |
| invalid | certficateExpired | Certificate got expired. Please upgrade the application. |
| invalid | invalidMobileChannel | Invalid mobile channel. |
| error | e2eDisabled | E2E is disabled. |
(FORBIDDEN) - Unauthorized to perform the requested operation on resource
| Type | Code | Details | More Info |
| invalid | accessNotConfigured | The request operation is not configured to access this resource | Channel/Country/Business provided in the request is not supported currently |
(INTERNAL SERVER ERROR) - API Server Error
| Type | Code | Details |
| fatal | serverUnavailable | The request failed due to an internal error/server unavailability |
Definitions
{
"required": [
"encryptedKey",
"checkDigit"
],
"type": "object",
"properties": {
"encryptedKey": {
"type": "string",
"description": "The symmetric key encrypted with static RSA public key .This is a dynamic key for every session",
"example": "93CDBEB681D937BAB1CED59789E02509A89BAD2407837D28CC32A80BFB7868BEEA202806CAD5B4E8F816F5507C3457CF752E3363B6F439F46855E9012715E6AA7DAF3AD02C681A12FB25C953092FC403B4E77B14E439BFF47C07CBB3AEFEAC28888997614BD925E5513B954CEFA3C945CE4B454638DBB69EC37A8B54E94A45A24A5F3AD9A5BEFB77A12EA1EEADCC3B023148929B5D8CBAC4325F311239CEB5B0F686549B008B6061529A26832B299209020FFB1B360AE6E01A7758ADBE843A63D3ABDA6862887010CBE35D8527B451D495883A278520D5E93787AA9105518DD9377F8F28F7C033F6EE6EFCE19648615C49ADE2F880DD113018B3FFD311FA55D646B1C79729D243D45A429C464DE2C43D"
},
"checkDigit": {
"type": "string",
"description": "The check digit of the symmetric key used to compare with the check digit value of the decrypted AES key in server.",
"example": "3A1AD9"
},
"algorithm": {
"type": "string",
"description": "The algorithm for manipulating the symmetric key. Currently only AES algorithm is allowed. Default is AES algorithm.",
"example": "AES"
}
}
}
{
"required": [
"type",
"code"
],
"properties": {
"type": {
"type": "string",
"enum": [
"error",
"warn",
"invalid",
"fatal"
],
"description": "
invalid - Request did not confirm to the specification and was unprocessed & rejected. Please fix the value and try again
warn - Request was partially processed. E.g. some of the fields are missing in response to the system issues, request was accepted successfully but will be processed asynchronously
error - The request was accepted but could not be processed successfully
fatal - There was an internal system error while processing the request. These are technical errors and will be resolved by Citi, and the consumer should retry after some time. Business errors will not be categorized as fatal "
},
"code": {
"type": "string",
"description": "Error code which qualifies the error"
},
"details": {
"type": "string",
"description": "Human readable explanation specific to the occurrence of the problem"
},
"location": {
"type": "string",
"description": "The name of the field that resulted in the error"
},
"moreInfo": {
"type": "string",
"description": "URI to human readable documentation of the error"
}
}
}