Auth

Newline requires access tokens and static IP addresses for authentication and authorization when making requests to any resource endpoints. POST /auth is used to obtain and refresh the required access tokens. In all environments, please work with your Relationship Team or the Newline Team to set up the IP Allowlist for your program.

To obtain an access token you must submit a refresh token. After a Program is set up, Newline 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>
}

2. Sign the JWT to create a JWS with the shared key using HS512 / SHA-512.
3. Exchange for an access token by sending a request to POST /auth, using the JWS in the Authorization header.
4. Access resources through other endpoints using the returned token in the Authorization header for up to 8 hours.
5. Repeat the process as needed to continue authenticating successfully.

Note that if a new access token is requested within the 8 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.