# Authentication

Our authentication is based on JSON Web Token ([JWT](https://datatracker.ietf.org/doc/html/rfc7519)) and JSON Web Signature ([JWS](https://datatracker.ietf.org/doc/html/rfc7515)).

Regardless of which programming language you are using, there should be [a library](https://jwt.io/libraries) 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`](https://datatracker.ietf.org/doc/html/rfc7515#appendix-C)). 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](#topic-getting-started)), and included in the HTTP headers of the request, as a standard bearer token `Authorization: Bearer <token>`.


## Example
_Example JWT header and payload_
```json
{
  "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"
}
```