JOSE

Wise uses the JOSE framework to accept and respond with signed and encrypted payloads. The following endpoints allow you to manage keys that apply to this process.

For more information, please speak with your Implementation team.

Endpoints
GET/v1/auth/jose/response/public-keys
POST/v1/auth/jose/request/public-keys
POST/v1/auth/jose/playground/jwe
GET/v1/auth/jose/playground/jwe

GET /v1/auth/jose/response/public-keys

This endpoint returns a public key issued by Wise for verifying signed HTTP responses and for encrypting payloads. These parameters must always be included.

For both signature verification and payload encryption, the process involves storing this public key after retrieval. In both cases, the stored public key should be used without calling this endpoint.

If verification of the signed request fails or you receive an encryption error, call this API once to issue a fresh key from Wise and then try verification one more time.

Parameters
versionstring

Fetch a specific public key version. If omitted the most recent public key is provided.

algorithmstring

Algorithm to be used for signature verification or payload encryption. This must match the algorithm used during request.

  • Signature verification (Scope: PAYLOAD_SIGNING): ES256, ES384, ES512, PS256, PS384, PS512
  • Payload encryption (Scope: PAYLOAD_ENCRYPTION): RSA_OAEP_256
scopestring

Scope of the signature. Value must be PAYLOAD_SIGNING or PAYLOAD_ENCRYPTION.

Response

Returns a public key object.

versionint

Version of the public key issued.

keyMaterial.algorithmstring

Algorithm to be used with the key. Values can be ES256, ES384, ES512, PS256, PS384, PS512, or RSA_OAEP_256.

keyMaterial.keyMaterialstring

Public key material.

scopestring

Scope of the key. Value will be PAYLOAD_SIGNING or PAYLOAD_ENCRYPTION.

Example Request
curl -X GET https://api.sandbox.transferwise.tech/v1/auth/jose/response/public-keys?algorithm=ES512&scope=PAYLOAD_SIGNING \
-H 'Authorization: Bearer <your api token>'
Example Response
{
"version": 1,
"keyMaterial": {
"algorithm": "ES512",
"keyMaterial": "MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQBYAwVICxD0Paq7MOuO34omujHxSrQXZtiTQ/VMteqAeUfM4wE+vTSpbYCqb1pNhhcQpF+FJd2H8jB1H1zil7qLLcBw+yl4PrnLza1pmNLr+kqQVoVXVyVx/xxMK2WObLn8tHxXtW4k+bm1/ySF+0RQ265IZcw2i8YYX2FY59JkwE2Fac="
},
"scope": "PAYLOAD_SIGNING"
}

POST /v1/auth/jose/request/public-keys

This endpoint allows clients to upload their public keys for request payload signing.

Parameters
keyIdstring

Unique public key identifier in uuid format.

validFromstring

The key is valid from the date in the format yyyy-MM-dd HH:mm:ss. The time zone is always UTC.

validTillstring

The key is valid till the date in the format yyyy-MM-dd HH:mm:ss. The time zone is always UTC.

scopestring

Scope of the payload operation.
Supported scopes are: PAYLOAD_SIGNING, PAYLOAD_ENCRYPTION.

publicKeyMaterial.algorithmstring

Algorithm to be used for:

  • Signature verification (Scope: PAYLOAD_SIGNING): ES256, ES384, ES512, PS256, PS384, PS512
  • Payload encryption (Scope: PAYLOAD_ENCRYPTION): RSA_OAEP_256
publicKeyMaterial.keyMaterialstring

Public key material in DER (Distinguished Encoding Rules) format and base64 encoded.

Response

Returns a 201 - Created and response object

keyIdstring

Unique public key identifier in uuid format.

validFromstring

The key is valid from the date in the format yyyy-MM-dd HH:mm:ss. The time zone is always UTC.

validTillstring

The key is valid till the date in the format yyyy-MM-dd HH:mm:ss. The time zone is always UTC.

scopestring

Scope of the payload operation.

publicKeyMaterial.algorithmstring

Algorithm to be used for request signature verification or for response payload encryption.

publicKeyMaterial.keyMaterialstring

Public key material in DER (Distinguished Encoding Rules) format and base64 encoded.

clientIdnull

This field is currently not in use and will always return null.

deactivationTimestampnull

This field is currently not in use and will always return null.

Example Requests
curl --location 'https://api.sandbox.transferwise.tech/v1/auth/jose/request/public-keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your api token>' \
--data '{
"keyId": "e87da464-8e5e-4380-8f2d-4e4e04052672",
"scope": "PAYLOAD_SIGNING",
"validFrom": "2023-04-27 00:00:00",
"validTill": "2024-04-01 00:00:00",
"publicKeyMaterial": {
"algorithm": "ES512",
"keyMaterial": "MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQBYAwVICxD0Paq7MOuO34omujHxSrQXZtiTQ/VMteqAeUfM4wE+vTSpbYCqb1pNhhcQpF+FJd2H8jB1H1zil7qLLcBw+yl4PrnLza1pmNLr+kqQVoVXVyVx/xxMK2WObLn8tHxXtW4k+bm1/ySF+0RQ265IZcw2i8YYX2FY59JkwE2Fac="
}
}'
curl --location 'https://api.sandbox.transferwise.tech/v1/auth/jose/request/public-keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your api token>' \
--data '{
"keyId": "9d09e43f-3c16-4683-9c07-db7e992b2050",
"scope": "PAYLOAD_ENCRYPTION",
"validFrom": "2023-04-27 00:00:00",
"validTill": "2024-04-01 00:00:00",
"publicKeyMaterial": {
"algorithm": "RSA_OAEP_256",
"keyMaterial": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwBjfPXePuZJr6jXEPibN8fpgysswqURHJGk5tod+T3SZBgVEXji0cuXF6xCdh7FMwIUROZ3ZsJFxOwyX8dNYzqEiiQy+C/wCr7/OzvRXQsy6qEQyW8fFsuEuqHRwb+ndAtz7HWZhq7P3K8XHCvJ72zeqZySXmxMYZDVwiwp+kMfRofLIivBjkN5DGWfn/7sxDLJr7/DdNgM1lMIHJtc3arffExROOnYkZ+UaUDxPo22Wnrdeb1h5S9s9m8Z46etMVEDbKJ7KEFppcRbMdckLnY3THZm/le5oxjrdVEDyhVioTC01NT0CTiqnNHfzB90ktWLsbKVww+bgDKAgx2x8EQIDAQAB"
}
}'
Example Response
{
"clientId": null,
"keyId": "e87da464-8e5e-4380-8f2d-4e4e04052672",
"scope": "PAYLOAD_SIGNING",
"validTill": "2023-04-27 00:00:00",
"validFrom": "2024-04-01 00:00:00",
"publicKeyMaterial": {
"algorithm": "ES512",
"keyMaterial": "MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQBYAwVICxD0Paq7MOuO34omujHxSrQXZtiTQ/VMteqAeUfM4wE+vTSpbYCqb1pNhhcQpF+FJd2H8jB1H1zil7qLLcBw+yl4PrnLza1pmNLr+kqQVoVXVyVx/xxMK2WObLn8tHxXtW4k+bm1/ySF+0RQ265IZcw2i8YYX2FY59JkwE2Fac="
},
"deactivationTimestamp": null
},
{
"clientId": null,
"keyId": "9d09e43f-3c16-4683-9c07-db7e992b2050",
"scope": "PAYLOAD_ENCRYPTION",
"validTill": "2023-04-27 00:00:00",
"validFrom": "2024-04-01 00:00:00",
"publicKeyMaterial": {
"algorithm": "RSA_OAEP_256",
"keyMaterial": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwBjfPXePuZJr6jXEPibN8fpgysswqURHJGk5tod+T3SZBgVEXji0cuXF6xCdh7FMwIUROZ3ZsJFxOwyX8dNYzqEiiQy+C/wCr7/OzvRXQsy6qEQyW8fFsuEuqHRwb+ndAtz7HWZhq7P3K8XHCvJ72zeqZySXmxMYZDVwiwp+kMfRofLIivBjkN5DGWfn/7sxDLJr7/DdNgM1lMIHJtc3arffExROOnYkZ+UaUDxPo22Wnrdeb1h5S9s9m8Z46etMVEDbKJ7KEFppcRbMdckLnY3THZm/le5oxjrdVEDyhVioTC01NT0CTiqnNHfzB90ktWLsbKVww+bgDKAgx2x8EQIDAQAB"
},
"deactivationTimestamp": null
}

POST /v1/auth/jose/playground/jws

This endpoint enables clients to send test signed HTTP requests and receive signed responses. Signing is mandatory for this API endpoint, any message that is not a JSON Web Signature (JWS) will be rejected.

Parameters
messagestring

Any text. For example: This is an example from docs.wise.com.

Response

Returns a 200 - OK and signed response object

messagestring

The response message will be prefixed with jose-playground-response- followed by the original message from the request. Please note that the message length is limited to 100 symbols.

methodstring

Original HTTP request method name: POST

Example Requests
curl -X POST --location 'https://api.sandbox.transferwise.tech/v1/auth/jose/playground/jws' \
--header 'Authorization: Bearer <your api token>' \
--header 'Content-Type: application/jose+json' \
--header 'Accept: application/jose+json' \
--header 'x-tw-jose-method: jws' \
--data 'eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsInVybCI6Ii92MS9hdXRoL2pvc2UvcGxheWdyb3VuZC9qd3MifQ.eyJtZXNzYWdlIjoiVGhpcyBpcyBhbiBleGFtcGxlIGZyb20gZG9jcy53aXNlLmNvbSJ9.AS9QHdkWvUEn0LxQEMPRBzlceN78J-Le-Qm1XIkkSBpsGdc0WM0MZTIGFEAJEcWeUR2M-abtd5DRdar4hLzs9apPAQ-GT70SIDV6pX9-4UKfIfzJ4g305zCoHflTfn-ijvI7XrVR_yr7xO9GJo86bfBqAX_m5uuxyU7Jy9gM1epd8HcC'
Example Response
eyJ2ZXJzaW9uIjoxLCJhbGciOiJFUzUxMiJ9.eyJtZXNzYWdlIjoiam9zZS1wbGF5Z3JvdW5kLXJlc3BvbnNlLVRoaXMgaXMgYW4gZXhhbXBsZSBmcm9tIGRvY3Mud2lzZS5jb20iLCJtZXRob2QiOiJQT1NUIn0.APYfoUySW_dPdBBVST3tJdaCBCMQZm0UR6g0vBqxjjX4WWkOdt6h045EXZKMT1m0JEMI5b7KpN14Mib9BxS7VWpLAPwYhTU5pJcQrtiK4fwaBMTT_DwipZk6ASXVevrMK_Tn9YSSkKDsv6X9qyBsnIXKy304Ex5QIHKmSGQT6wNSJ7Ye02
Example of Decoded Response
{
"message": "jose-playground-response-This is an example from docs.wise.com",
"method": "POST"
}

POST /v1/auth/jose/playground/jwe

This endpoint enables clients to send test encrypted HTTP requests and receive encrypted responses. Encryption is mandatory for this API endpoint, any message that is not a JSON Web Encryption (JWE) will be rejected.

Parameters
messagestring

Any text. For example: This is an example from docs.wise.com.

Response

Returns a 200 - OK and encrypted response object

messagestring

The response message will be prefixed with jose-playground-response- followed by the original message from the request. Please note that the message length is limited to 100 symbols.

methodstring

Original HTTP request method name: POST

Example Requests
curl -X POST --location 'https://api.sandbox.transferwise.tech/v1/auth/jose/playground/jwe' \
--header 'Authorization: Bearer <your api token>' \
--header 'Content-Type: application/jose+json' \
--header 'Accept: application/jose+json' \
--header 'x-tw-jose-method: jwe' \
--data 'eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.W_WPBDXclMryaywqAB-_yC1hUYukKmZxByhE9d1G8hClc2HpewkryILGJW4uVTUeRdo1oVWd68TPIqi7bqMGUsrT-3MI4ggVSjC1rf8Lf1xTZ8-GHjSPso8tFBXnydOKzggi6fnfk98BIW76Rnxkn6sW79LH5NgN1spTOoh8-tI3i_wbHdqJOxTReaUNMYZobm7wxedZcRxhsaSrVqx2qdELeqkfwgvB1DRbHTF_PTe4W0ibMbcJivHjiDf6oAV9vXgVhYb66rhB43pgdFDv4nY1mkQC45R5T6CBdzv80EdAVOj1G4bktHyJWaJzHVsGozpxsNj3bt1AopyvDO8tsw.WLOO5WH4ZpBPi-8B.0g3eUpQPvRIaTbgUi6sH0WejsJ1nLWDGnDKTktZrkquLQlCMmIguj0I5UCyqXEo.URtTniRvfGxrKRLK63trug'
Example Response
eyJraWQiOiI2ZGE0OTQ5NS0xNjMyLTQzY2QtOWEwMy1kZDMyNDYwM2VjZDciLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.qwMqgFXRI84THQdCHhxNe5yvKOuKp2rAMH62xQ1OioPatnLfxqPHJUX0as13B3g3JKaqGgF0qMi7r3QbJ_cXNFBIg1yenCwWv4192J73-kEkCSyS-FflDCNfih1z1mm95ftAE7FhHJVG5tcSm_B0-bPU3SbjB3SDhR3QlLX5o_sQmYkQay8PKSssyBS5tCjuKdz-9QNvZtNADPujKrJGe5hE5r7ShcNwVUS2vpMXANiQTzZnQ2L3j_m07Rru-PgMxHTD2uR621B87YfTHonWDJe4XogA_pMWD_hzHVQKT7Il--2YOtv8PTnLge-uVvRTgqUiYUdvq85nPyDKsOQMnQ.zprknKK9W4iAX7YA.LJWA6oRcYj0LruM3GLPtZ0CtVNpI0Zs9WFrARDd464kKxSlu15LBiFFCFwOHbeKoRudfp8Br7MfRIlaTLHxPEE1xoBB8jZN8fakAcApU.OlMATtfF9XMtYJtTsGuBGQ02
Example of Decrypted Response
{
"message": "jose-playground-response-This is an example from docs.wise.com",
"method": "POST"
}

GET /v1/auth/jose/playground/jwe

This endpoint enables clients to send test HTTP GET requests and receive encrypted responses.

Response

Returns a 200 - OK and encrypted response object

messagestring

The response message is always jose-playground-response-.

methodstring

Original HTTP request method name: GET

Example Requests
curl -X GET --location 'https://api.sandbox.transferwise.tech/v1/auth/jose/playground/jwe' \
--header 'Authorization: Bearer <your api token>' \
--header 'Content-Type: application/jose+json' \
--header 'Accept: application/jose+json' \
--header 'x-tw-jose-method: jwe'
Example Response
eyJraWQiOiI2ZGE0OTQ5NS0xNjMyLTQzY2QtOWEwMy1kZDMyNDYwM2VjZDciLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.UC5mC6XSGZZuQzUALpM2QfDWyi-lcl4Wv3v8-9L04BFmqYTyiQMO-YMxiwzOdVbF-L01CaFcr_iuoM36fKp01onJAtsrvuGcnrHeh23kMwZ5k29ycGTckE0YYLe-WV9WtXguudfFC3Hri9v4FTPEE1_BbkrHACVufuhw_xWUWgYAekfm7dnmTI_3SmtExWZ_P-Xn6rkGXhsJ0Kq9LB-F3mnuvz_iglvZsW76RdLV_I4es-TfTnQgVOGO-N38SSS4wCF1qw2TWOkpNAe9kyAg6a8tWw8ZkpOxJlmGdp4jLuG_GDWlmtDrv9ntgeCLDRiTp4SLYL2MGYdmNXigZI5xrg.P_h3CuIiKxEzndER.Zf0wahZEHQSMcb4olkeT1NNzh3Alj34XbXVdREiqQH9CKDa-GnKvh1lXXYuvTO99vtBmNRM.iTzGQ3FNRIybDT_lJcnaeQ03
Example of Decrypted Response
{
"message": "jose-playground-response-",
"method": "GET"
}