Auth

The Authentication section explains how to securely interact with Newline's API using access tokens and static IP addresses. Learn how to generate and refresh tokens to access protected resources.
Endpoints:

• POST Generate an authentication token: POST /auth

Newline requires access tokens and static IP addresses for authentication and authorization when requesting any resource endpoints. POST /auth is used to obtain and refresh the required access tokens. Please work with your Relationship Team or the Newline Team in all environments 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 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

If a new access token is requested within the 8 hours of a previous token being successfully exchanged, the new token will still be generated. This does not expire the last 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.