Rize requires access tokens for authentication and authorization when making requests to any resource endpoints. POST /auth is used to obtain and refresh the required access tokens.

To obtain an access token you must submit a refresh token. After a Program is set up, a Rize account manager will share your Program UID and HMAC key with you offline. These values are required for the refresh token and access token requests.

The authentication flow is as follows:

  1. Create a JWT using the following claim:
  "iat": <current Epoch time>,
  "sub": <Program UID>
  1. Sign the JWT to create a JWS with the shared key using HS512 / SHA-512.
  2. Exchange for an access token by sending a request to POST /auth, using the JWS in the Authorization header.
  3. Access resources through other endpoints using the returned token in the Authorization header for up to 24 hours.
  4. Repeat the process as needed to continue authenticating successfully.

Note that if a new access token is requested within the 24 hours since a previous token has been successfully exchanged, the new token will still be generated. This does not expire the previous token and both tokens are usable simultaneously until their respective time is up. However, it is encouraged to use the new token and discard the old one if possible as this behavior may change in the future.