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?algorithm=ES512&scope=PAYLOAD_SIGNING
POST/v1/auth/jose/request/public-keys

Get Wise public signing key

GET /v1/auth/jose/response/public-keys?algorithm=ES512&scope=PAYLOAD_SIGNING

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

The process involves storing this public key after retrieval. Attempts to verify a JWS response should be done with a previously fetched key. If verification fails, call this API once to issue a fresh key from Wise and then try verification one more time.

Supported algorithms are: ES256, ES384, ES512, PS256, PS384, PS512, RSA_OAEP_256, RSA_OAEP_384, RSA_OAEP_512.

Parameters
versionstring

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

algorithmstring

Algorithm to be used for response signature verification. This must match the algorithm used during request signing.

scopestring

Scope of the signature. Value must be PAYLOAD_SIGNING, which is the only scope we support at present.

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 ES512.

keyMaterial.keyMaterialstring

Public key material.

scopestring

Scope of the key. Values will be PAYLOAD_SIGNING.

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": "MIGeMA0GCSqGSIb3DQEBAQUAA4GMADCBiAKBgG+BRBc/UZG2fX0xaPXpl5kW191p
                        1tkmnXGHoaiVNbI3lC4wpPBfEP4tZIXLm90+dGsdnxE1SJeoiZIFJ+swRmAwKx
                        Kj7i2xMMAg3AU3bZs3hPLznX5vLUzyGLC6V3bS0UuvL4uKPQTyEJV5RKHnXnhgRQ
                        j/5Yt9J4xh7OtJtTAgMBAAE="
    },
    "scope": "PAYLOAD_SIGNING"
}

Add a new client public key

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 signature. Value must be PAYLOAD_SIGNING, which is the only scope we support at present.

publicKeyMaterial.algorithmstring

Algorithm to be used for request signature verification.
Supported algorithms are: ES256, ES384, ES512, PS256, PS384, PS512, RSA_OAEP_256, RSA_OAEP_384, RSA_OAEP_512.

publicKeyMaterial.keyMaterialstring

Public key material.

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 signature. PAYLOAD_SIGNING is the only scope we support at present.

publicKeyMaterial.algorithmstring

Algorithm to be used for request signature verification.

publicKeyMaterial.keyMaterialstring

Public key material.

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 Request
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="
    }
}'
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
}