JSON Web Signature (JWS)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Learn how JOSE JWS works with Wise Platform.

JSON Web Signature (JWS) is the JOSE standard that provides a framework to digitally sign JSON content.

Implementing JWS in your system ensures the sender's identity and message haven't been altered, providing non-repudiation for your interactions with the Wise API.

Summary of the signing process:

1. Create a key pair and deliver the public key to Wise.
2. Wise installs the public key to be consumed by the Wise API.
3. Once installed, you can call JWS enabled endpoint with signed request bodies.
4. Wise verifies the signature using the public key provided and performs additional checks, including the validity of the URL.
5. Wise returns the response encoded and signed.
6. Your system verifies and decodes the header and payload from the returned JWS.

Providing public keys

You can upload your public JWS key in Developer Hub. If you do not yet have access to Developer Hub, contact your implementation team for access.

Alternatively, you can upload public keys via API.

JWS key properties

Upload JWS via Developer Hub

1. Log in to Developer Hub:
   • Sandbox testing: Log in to the Developer Hub sandbox with your sandbox credentials.
   • Production: Log in to the Developer Hub (production) with your production credentials.
2. Go to Authentication → JOSE.
3. Make sure you are on the JWS (Signing) tab and then click Upload new JWS key.
4. Enter your public key details:
   • Paste your public key material.
   • Choose the algorithm that matches your key type.
   • Enter the unique Key ID (kid in UUID format).
   • Set the Valid From and Valid Until fields. The Valid Until field determines when the key expires.

After upload, the new key appears in the JWS list alongside any existing keys.

Manually signing a request

Here is a step-by-step workflow, with example commands, to manually sign a request.

Create request headers & body

Create the required request body for the REST endpoint you wish to call, as well as the JWS header with required parameters. These will be signed in the next stage.

Required JOSE header parameters for JWS:

{
  "alg": "ES512",
  "typ": "JWT",
  "kid": "663a0e44-aa4a-4ff0-a9f8-cd99f5fbad71",
  "url": "/v3/profiles/12345/transfers/12345/payments"
}

{
  "type": "BALANCE"
}

Sign with private key

We accept JWS requests as JWTs using JWS compact serialization as defined in the JOSE standard for JWS.

We recommend you use an established library to complete this process to avoid difficulties and errors in the encoding and signing process.

Here is an example of the previous payload and header block signed using JWS compact serialization:

ewogICJhbGciOiAiRVM1MTIiLAogICJ0eXAiOiAiSldUIiwKICAia2lkIjogIjY2M2EwZTQ0LWFhNGEtNGZmMC1hOWY4LWNkOTlmNWZiYWQ3MSIsCiAgInVybCI6ICIvdjMvcHJvZmlsZXMvMTIzNDUvdHJhbnNmZXJzLzEyMzQ1L3BheW1lbnRzIgp9
.ewogICJ0eXBlIjogIkJBTEFOQ0UiCn0=
.Z-B7ScaZ37U_0CKrv03LTi0O0GWR2Hm5shzoEj8xRmM

Submit authenticated API request

The request must include the following headers:

• Content-Type: application/jose+json
• Accept: application/jose+json
• X-TW-JOSE-Method: jws

curl -X POST 'https://api.transferwise.com/v3/profiles/12345/transfers/12345/payments' \
     -H 'Authorization: Bearer XXXXXXX' \
     -H 'Content-Type: application/jose+json' \
     -H 'Accept: application/jose+json' \
     -H 'X-TW-JOSE-Method: jws' \
     -H 'Accept-Encoding: identity' \
     -d 'ewogICJhbGciOiAiRVM1MTIiLAogICJ0eXAiOiAiSldUIiwKICAia2lkIjogIjY2M2EwZTQ0LWFhNGEtNGZmMC1hOWY4LWNkOTlmNWZiYWQ3MSIsCiAgInVybCI6ICIvdjMvcHJvZmlsZXMvMTIzNDUvdHJhbnNmZXJzLzEyMzQ1L3BheW1lbnRzIgp9.ewogICJ0eXBlIjogIkJBTEFOQ0UiCn0=.Z-B7ScaZ37U_0CKrv03LTi0O0GWR2Hm5shzoEj8xRmM'

Verify the response

The response is a fully formed JWT using compact serialization.

Verify the response by fetching the latest Wise public key and checking the signature. See Get Wise JWT public key for details.

Wise signs the response using the same algorithm used to sign the request body.

If there is no body in the original request, the ES512 algorithm will be used to sign the response.

  $ curl -i -X GET 'https://api.wise-sandbox.com/v1/auth/jwt-public-key?algorithm=ES512&scope=PAYLOAD_SIGNING' \
         -H 'Content-Type: application/json' \
         -H 'Authorization: Bearer <your api token>'

Rotating JWS keys

We recommend rotating your keys at least once every 12 months. However, you can rotate your keys as often as your security protocols require.

For steps to rotate your JWS keys, see the Rotate JWS keys guide.

Troubleshooting

Use this section to diagnose common JWS failures.

Signature verification failure

400 Bad Request response:

{
  "error": "jws_error",
  "error_description": "Unable to verify the request signature"
}

This means Wise received your JWS but could not verify the signature.

Common causes:

Malformed request error

A 400 or 422 response indicating a malformed or invalid request body, even though your payload JSON is correct.

Cause: The required JOSE HTTP headers are missing or incorrect. Without these headers, Wise does not detect the request as a signed JWS and attempts to parse the JWS compact serialization as plain JSON, which fails.

Solution: Ensure all three required headers are present on every JWS request:

Content-Type: application/jose+json
Accept: application/jose+json
X-TW-JOSE-Method: jws

Unexpected server error

500 Internal Server Error with a generic message:

{
  "message": "An unexpected error occurred",
  "request_id": "..."
}

Common causes:

Empty or null response body

The request appears to succeed but the response body is empty or null.

Cause: The Accept-Encoding HTTP header is set to gzip. Wise does not currently support compressed encoding for JOSE responses, which can result in the response body being silently dropped.

Solution: Set the Accept-Encoding header to identity:

Accept-Encoding: identity

Wrong environment

Requests fail with verification errors even though signing works in another environment.

Cause: Signing keys are environment-specific. Keys uploaded in sandbox are not available in production, and vice versa.

• Sandbox: Upload keys via Developer Hub sandbox and send requests to api.wise-sandbox.com.
• Production: Upload keys via Developer Hub and send requests to api.wise.com.

Diagnostic checklist

1. HTTP headers: Confirm Content-Type: application/jose+json, Accept: application/jose+json, and X-TW-JOSE-Method: jws are all present.
2. Accept-Encoding: Set to identity, not gzip.
3. kid header: Present in the JWS protected header and matches the Key ID of an active key in Developer Hub for the correct environment.
4. url header: Matches the actual API endpoint path in the request.
5. Algorithm: The alg in your JWS header matches the algorithm your key pair was generated with.
6. Key pair: You are signing with the private key that corresponds to the public key uploaded to Wise.
7. Environment: You are using keys and endpoints from the same environment (sandbox or production).

Contacting support

When contacting Wise about a JWS issue, include:

• The x-trace-id from the response headers.
• The HTTP status code and full response body.
• The environment (sandbox or production).
• The kid you are using.

This helps the support team diagnose the issue quickly. Contact api@wise.com.