EQ API

Number of APIs: 17

EQ API services all client-side transactions via a REST API. All protected routes use JWT Token based authentication.

Obtaining a JWT:

Composition

EQ uses a one-time passcode based login for authentication and authorization. This replaces the previous API key based authentication.

Workflow

In order to support the growing number of products the base URL needs to specify the stage component. As a result, authentication is now a standalone service for each product. The base URL is https://auth.eqworks.io/<stage> where <stage> are either dev or prod.

Step 1: Login

user, end-user’s email address is placed in <user email>. This is required and must already be in EQ’s user database.
redirect, optional redirect URL, detailed example below.
zone, default is UTC, can be set to a preferred timezone.
product, now mandatory serves the purpose to scope the provisioned JWT depending on API resources. Depending on the product in use place atom or locus in the <product name> space.
```
`https://auth.eqworks.io/<stage>/login?user=<user email>&zone=<zone>&product=<product name>`
```

The most important change here is the redirect query string parameter which enables the API application to seamlessly integrate through the custom “magic-link”. user and product are the only parameter that persist, therefore store the magic-link somewhere safe .

For example:

https://report.ui.project/login?a=1&b=2&user=sue.sxxxxht@gmail.com

The generated “magic-link” will be:

https://report.ui.project/login?a=1&b=2&user=sue.sxxxxht@gmail.com&otp=<OTP>

The URL report.ui.project will use the OTP contained within the generated “magic-link” for the next step.

If using a hardcoded redirect URL make sure it is encoded.

If no redirect is supplied, the default “magic-link” would route back to https://auth.eqworks.io/<stage>/verify?user=sue.sxxxxht@gmail.com&otp=<OTP generated>. This would be the URL to compose for next step.

The “magic-link” and the plain-text OTP will be delivered to user’s email.

Step 2: Verification

Verification is done through https://auth.eqworks.io/<stage>/verify. The required query string parameters are the query string [user,JWT] provided through the “magic-link” sent in the email.

Upon success, this will yield the following response:

{
  "message": "User sue.sxxxxht@gmail.com verified, please store and use the attached token responsibly",
  "user": "sue.sxxxxht@gmail.com",
  "token":"<the JWT, redacted>"
}

Note that for now, JWT is set to expire in 90 days. However this can reset for another 90 days as per step 4.

Subsequent data requests can all be made to appropriate stage api.eqworks.io. Examples of different data requests are displayed below and organized by product. You can select the preferred coding language from the LANGUAGE dropdown menu.

Be sure to supply the JWT within the custom HTTP header. We recommend to include user as well. For example: { eq-api-user: user, eq-api-jwt: jwt, }

Step 3: Validate JWT (Optional)

This step may be utilized as a method for validating the legitimacy of the JWT. The endpoint is https://auth.eqworks.io/<stage>/confirm and the JWT must be supplied through custom Header eq-api-jwt.

An optional light query string parameter is included for verification, but its integrity will not be validated against the system back-end. If a light query is not supplied and the return validation is false or 0, the system will perform an integrity check against the user database.

STEP 4: JWT Expiry Reset (OPTIONAL)

The following is a simple way to reset the JWT expiry time and date. As a guideline JWT expiry times should be reset prior to the current expiration date and time set.

The refresh endpoint is https://auth.eqworks.io/<stage>/refresh, and is similar to the confirm endpoint with the exception of no light quey option. The response will include a new token with the new expiration date/time.