Our authentication is based on JSON Web Token (JWT) and JSON Web Signature (JWS).

No matter which coding language you are using, there should be a library to handle the cryptographic part for you. All you need is to feed it the right header and payload claims.

In the JWT header:

  • alg must be RS256, as we require a RSA-SHA256 signature.
  • typ must be JWT.
  • x5t#S256 is the SHA256 thumbprint of the certificate, which you can find on the user interface.

In the JWT payload:

  • sub must be the method of the request, followed by a space and the full path, including query params.
  • aud must be the domain on which you do the request, e.g.
  • iat must be the timestamp at which you created the token. Note that we accept only 5 seconds of difference with the server time, to mitigate clock skew.
  • jti must be a unique identifier for the token. It must be different for each request and respect the UUID format.
  • sec must be the secret information you obtained during the setup process on the user interface. This is a custom claim, not covered by the JWT specification.
  • dig#S256 must be a base64url_encoding(sha_256(body)), to be provided only if the request has a body, so for example it is not necessary on GET requests (see base64url_encoding). This is a custom claim, not covered by the JWT specification.

The JWT must then be signed with the private key you generated during the setup (see Getting started), and included in the HTTP headers of the request, as a standard bearer token Authorization: Bearer <token>.

Example JWT header and payload

  "alg": "RS256",
  "typ": "JWT",
  "x5t#S256": "3A14ZcxIaasp4RHaYReL7wevm3oDzn7ZqmgqScCMY74"
  "sub": "POST /v1/transfers",
  "aud": "",
  "iat": 1657055009,
  "jti": "5525620b-9dcd-4562-8c6c-60984f46cb48",
  "sec": "a2029d646c94406d2945b7a2b31e4fb3ff09a6d0ae29144380775b5471c4e846",
  "dig#S256": "lW6N_kO2gPMsMkzXyn028gWwrnaN0kJaiy7FMJcR0Ek"