Authentication

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

Regardless of which programming language you are using, there should be a library to handle the cryptographic part for you. All you need is to provide the correct header and payload claims.

In the JWT header:

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

In the JWT payload:

  • sub must be the request method, followed by a space and the full path, including query parameters.
  • aud must be the domain to which you are making the request, e.g., api.memo.bank.
  • iat must be the timestamp at which you created the token. Note that we accept only a 5-second difference from the server time to mitigate clock skew.
  • jti must be a unique identifier for the token. It must be different for each request and follow the UUID format.
  • sec must be the secret information you obtained during the setup process in 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; for example, it is not necessary for 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": "api.memo.bank",
  "iat": 1657055009,
  "jti": "5525620b-9dcd-4562-8c6c-60984f46cb48",
  "sec": "a2029d646c94406d2945b7a2b31e4fb3ff09a6d0ae29144380775b5471c4e846",
  "dig#S256": "lW6N_kO2gPMsMkzXyn028gWwrnaN0kJaiy7FMJcR0Ek"
}