# JSON Web Encryption (JWE)

Learn how JOSE JWE works with Wise Platform.

JSON Web Encryption (JWE) is a JOSE specification that defines a compact and URL-safe way to represent encrypted content. Implementing JWE ensures that only the intended recipient can read the JSON request, providing confidentiality for sensitive data exchanged with the Wise API.

Here's a summary of how the encryption process works:

1. Create a key pair and deliver the public key to Wise, which Wise will use for response encryption.
2. Request Wise's public key and use it to encrypt the request.
3. Once step 1 and 2 are complete, encrypt a request body and make a call to the Wise API.
4. Wise decrypts the encrypted request using its private key and then performs additional checks.
5. Wise returns the response encrypted with the provided public key.
6. Your system decrypts the payload from the returned JWE.


## Providing public keys 

Wise allows you to [upload public keys via API](/api-reference/jose/joserequestpublickeyscreate).

### Encyption key requirements

* Algorithm set to `RSA_OAEP_256`
* Scope set to `PAYLOAD_ENCRYPTION`


## Using JWE endpoints workflow 

Here is a step-by-step workflow, with the required information, for successful request encryption.

Wise uses a standard implementation of JOSE JWE. For more information on constructing, encrypting, and decrypting JWE, see [JSON Web Encryption (JWE)](https://www.rfc-editor.org/rfc/rfc7516).

### 1. Create request JWE headers

Create a request body according to the usual API reference (see example).

Required JWE headers:

| Header | RFC |
|  --- | --- |
| alg | [RFC-7516 section-4.1.1](https://www.rfc-editor.org/rfc/rfc7516#section-4.1.1) |
| enc | [RFC-7516 section-4.1.2](https://www.rfc-editor.org/rfc/rfc7516#section-4.1.2) |


Currently, we only support the `RSA-OAEP-256` algorithm and the `A256GCM` content encryption algorithm. For further support of other algorithms and encryption methods, contact your implementation manager.

JOSE headers

```json
{
  "alg": "RSA-OAEP-256",
  "enc": "A256GCM"
}
```

Payload to be encrypted

```json
{
  "type": "GENERAL_ENQUIRY",
  "subject": "Inquiry about Transfer 12345",
  "details": {
    "transferId": 58114690,
    "profileId": 14556049,
    "userId": 1234
  },
  "externalId": "partner_external_id_12345",
  "description": "Initial summary of the issue"
}
```

### 2. Encrypt the message

Wise only supports JWE with Key Encryption employed, a Key Management Mode in which the CEK value is encrypted to the intended recipient using an asymmetric encryption algorithm.

Supported cryptographic algorithms:

| Name | RFC |
|  --- | --- |
| RSA-OAEP-256 | [RFC-7518 section-4.1](https://www.rfc-editor.org/rfc/rfc7518#section-4.1) |


Supported content encryption algorithms:

| Name | RFC |
|  --- | --- |
| A256GCM | [RFC-7518 section-5.1](https://www.rfc-editor.org/rfc/rfc7518#section-5.1) |


Wise does not re-use the request CEK for response encryption. Instead, we generate a new CEK for every response.

Encrypted HTTP request body example

```sh
eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0
.nzXdYfoI1X-4RVKuPp4U1b7oRGjz8zp5mqU-Otag0GUczxmifX3OqxBqMirfvdZXLdV6GgIyxZxlFeuF9C94cuFaIkA1frZy6bp-gY6dNrXTWebka34SWFwCNL8hfyzDRcWs6mQ0BNL5ALUfA3NO8Xh98yUSk1dnIMSHZvLd0feIP-1rYYDJsacIMnWA9zUjzY-rTsQbrzziGKtCvmRyzJAaCYfiYOAh-UjkmAhc5-xd3XPzqKeF-QaIGd0KTrr_Wucdq9CZsuEjXhKWfU27hacDtKaG_khUOKWfWTwoThRjfO9ckuO2oeB4UGLZ36IFSlMQ48p9s4PgnMg2YDCOrg
.fx2-MHbRsutByyOm
.d8MhWJo5Ih_fvTAmBGjfUMR5wc1V74ZS65Xy7Xx5MEAU8DEPbu1cQBu9U9l4BUZ2iR637C_JSo44EqDE26dDiow6LM-GIM-WWsR5f50A1_7vf89fJR4zfH6hob6g9YC-gMMTJ50x6fhspI1vBmXWvt4uXPmO4HTs06Rl3gs1jXyoA5_3A58IsFV1POMX3DUVPhKEVQwtlUtXgfEdyXXHnO854wWNbi7_pyn2vPABS_CyZy74JJGjDWovONRFZ81OkLGmyb2jQcQxlfetZz5wTbcQ86m-AGcf3nw41y4xXn8hODjGwnYY1BiSvZOt2kOmEGRaMHr2s3kTlhZ6rPJoLjodBkbUBM_W0g
.Sewt5vM_AClXhdCBVNbWyQ
```

For instructions on encrypting messages, please refer to [RFC-7516 section-5.1](https://www.rfc-editor.org/rfc/rfc7516#section-5.1).

### 3. Submit authenticated API request

The Wise public API supports using JWE for all HTTP request methods, including those without an expected HTTP request body, such as GET requests. Upon receiving an HTTP request without a body, the Wise API performs only response payload encryption.

The request must include the following headers:

* `Content-Type: application/jose+json`
* `Accept: application/jose+json`
* `X-TW-JOSE-Method: jwe`


Complete POST request

```bash
curl -X POST 'https://api.transferwise.com/v1/cases' \
     -H 'Authorization: Bearer XXXXXXX' \
     -H 'Content-Type: application/jose+json' \
     -H 'Accept: application/jose+json' \
     -H 'X-TW-JOSE-Method: jwe' \
     -H 'Accept-Encoding: identity' \
     -d 'eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2IiwidXJsIjoiL3YxL2Nhc2VzIn0.B9g-Z3eJrKFK7eALNjL363ZXHn_us_axnfIJqB4GH8ayvL2QvK8OVlrONI3HGlq80zNzaFGSugzMzptJeQxa3jz92QK3Ks-JVRUH9vEMe99fDEuvvIWHKRA-yuCs1UBRSYjt1NxskX9Vo97xmjzLyy5ysOrz5SJYJj2okKnZ7DZuNNfZ7m6wKqxFJDJ2S_y6uJQXGiv5isip1WGd54qagiK5L_9pACZNBAG9IBErojY8L0xruCjkt1-2jktyDa6t1euER_CSstiYM55Lie2EZKnDKVIJ1zOuOEqMPOFEbwNhZaJyspNiWeu0l87zo7K8_Vu6VCeSaVo0fvH7Fm6Dtg.yenUpQ_KISjo0JMk.nk5h-UKewy4wJsCk2prAK5bmUbc-PQEPHW3YtxUMBk8u5X59bHXOsol5H4foKPeRvUIw8lx-yOLck2pvh7QESUoiWSwVguuKn3w-V3AdhhTXm6Bzij_6wndusILAHThBHlwRrUuU1amG69nNxDsLNv_zmZ1ZSZfwJz01sy6dcKEolD4xH72hPIBYKrNk5ihkiV8DgzTVF-rAcBODTQ10PTd4ZWIDsvTGL49neD9WcLMVpaUwG8NMOARY4w_pr0ikTlcjFUP2vOFhq6I1KwxrRJFRNb60ifY2w-_-2Dmab4kWtwTFrkFCj2T8hUV0vZQcYldxUGCDPnSIPaHk_x9O-y66lMwyyi70ug.AMyL0XyQJ6roHeGAc_Du1Q'
```

Complete GET request

```bash
curl -X GET 'https://api.transferwise.com/v1/cases/123456789' \
     -H 'Authorization: Bearer XXXXXXX' \
     -H 'Content-Type: application/jose+json' \
     -H 'Accept: application/jose+json' \
     -H 'X-TW-JOSE-Method: jwe' \
     -H 'Accept-Encoding: identity'
```

### 4. Decrypt the response

The Wise API is designed to enhance security by encrypting HTTP responses. When a JWE is used in an HTTP request, Wise responds with a JWE message. The response encryption algorithm and the content encryption algorithm are matched with those used in the initial HTTP request. Additionally, Wise includes the public key ID, which was used for encrypting the response payload, as part of the `kid` (Key Identifier) in the JOSE header.

The Wise API does not apply encryption or modify HTTP headers for empty responses.

Response JOSE headers

```json
{
  "alg": "RSA-OAEP-256",
  "enc": "A256GCM",
  "kid": "663a0e44-aa4a-4ff0-a9f8-cd99f5fbad71"
}
```

For instructions on decrypting messages, please refer to [RFC-7516 section-5.2](https://www.rfc-editor.org/rfc/rfc7516#section-5.2).

### 4a. Decrypt directly encrypted response

The Wise API supports end-to-end application-level encryption, which can be used for securing requests between mobile clients and Wise. In this scenario, the response encryption is implicitly handled using direct encryption. Wise employs the original content encryption key used in the request to encrypt the response.

Response JOSE headers

```json
{
  "enc":"A256GCM",
  "alg":"dir"
}
```

For more information about direct encryption, refer to [RFC-7518 section-4.5](https://www.rfc-editor.org/rfc/rfc7518.html#section-4.5).