Authentication for RESTful API Queries

To enable digital signatures and encryption:

1. Select Admin in the toolbar in the upper-right corner of the window.

   The System Administrator Dashboard page opens.

2. Click Manage Features / Global Properties link in the Data / PS Tools section.

   The Manage Features page opens.

3. Click Manage Firm (Lx) Properties tab.

   The Manage Firm (Lx) Properties tab opens.

4. Select RESTful from the menu above the table.

   The RESTful API configuration options appear.

5. Click Add Global Property in the lower-right portion of the table.

   The Add Global Property window opens.

6. Enter Sign in the Key field.

7. Enter true in the Value field.

8. Select Add.

   The window closes. The new firm-specific property appears in the table. The digital signature is enabled.

9. Click Add Global Property in the lower-right portion of the table.

   The Add Global Property window opens.

10. Enter Encrypt in the Key field.

11. Enter true in the Value field.

12. Select Add.

    The window closes. The new firm-specific property appears in the table. Encryption is enabled.

The IWMS-generated JWT token can have a limited lifespan if your account is affected by the company password policy. This means that the token's expiration is subject to the Days Until Password Expires setting on in the Password Policy page, unless:

• the member fetching the token is exempt from the password policy

• the expiration is set for a shorter period in the POST call

Once the token expires, you will have to get a new JWT token via the Copy [JWT Bearer Authentication token] to Clipboard.

You can acquire either a basic or bearer token that represents your account by navigating to the RESTful Webservice Docs page within Lucernex.

To retrieve the Lucernex authentication token:

1. Select Admin in the toolbar in the upper-right corner of the window.

   The System Administrator Dashboard page opens.

2. Click RESTful WebService Docs link in the Data / PS Tools section.

   The RESTful WebService Docs page opens.

   Not all users can see the RESTful WebService Docs link. If you don’t see it, you can access it at the following URL: {{url}}/en/test/RESTful.jsp

3. Do one of the following:

   • Click Copy Basic Authentication token to Clipboard.

     Getting your Basic Authentication token has the advantage that the password is SHA-1 encrypted. This improves security because it is impossible to determine the plaintext equivalent password.

   • Click JWT Bearer Authentication token to Clipboard.

     The appropriate token is copied to your clipboard.

     IWMS-generated JWT tokens are only accepted by the IWMS environment that created said token.

4. Paste the authentication token into what ever RESTful client you are developing.

5. Click OK.

   The dialog box closes.

You can generate a JWT Bearer token via API call with the jwt resource which includes an optional expiresOn parameter. If the expiresOn parameter is omitted, Lucernex enforces the firm-defined password expiration policy as it applies to the user making the call.

In the following procedures, we explain how to get a JWT Bearer token using Postman, a free API development software.

To get a JWT token via a RESTful call in Postman:

1. Click Authorization tab.

2. From the TYPE list, select Basic Auth.

3. In the Username field, enter your username and firm name in the following syntax: username:firmName.

   The username is case sensitive. The firm name is not.

4. In the Password field, enter your password.

5. Change the method to POST.

6. Add the URL: {{url}}/rest/jwt.

7. If necessary, add the expiresOn parameter with the expiration date and time in the ISO 8601 format.

   If you don't provide the optional TZD part of the timestamp, then the provided timestamp is considered to be relative to the IWMS server’s timezone or CT.

   Syntax: yyyy-MM-dd'T'HH:mm:ss.sTZD

   • Example without URL encoding: 1997-07-16T19:20:30.45+01:00

   • Example with URL encoding: 1997-07-16T19:20:30.45%2B01:00

   Syntax variable definitions

   Variables	Definition	Limits	Sample
   yyyy	4-digit year	N/A	1997
   MM	2-digit month in year	01 to 12	07 = July
   dd	2-digit day in month	01 to 31	16
   T	Time delimiter	N/A	T
   HH	2-digit hour in 24-hour day	00 to 23	19
   mm	2-digit minute in hour	00 to 59	20
   ss	2-digit second in minute	00 to 59	30
   S	1 or more digits as a decimal fraction of a second	1 to 9 or 01 to 99 or 001 to 999	45
   TZD	Time zone designator Z for UTC time +|-hh:mm for UTC offset +|- = direction of offset hh = hours of offset mm = minutes for offset	Z or + (encoded as %2B) - (unencoded) hh = 00 to 14 mm = 00, 30, 45	%2B01:00

8. Click Send.

   The response body will contain the token without the Bearer prefix. Copy the token and use it in the following procedures.

Once you have obtained the Bearer token, you can use it to make subsequent calls by passing it as a header parameter.

In the following procedures, we explain how to use a JWT Bearer token in Postman, a free API development software.

To use the bearer token in Postman:

1. Copy the token you received in the previous procedures.

2. Click Authorization tab.

3. From the TYPE list, select No Auth.

4. Click Headers tab.

5. In the Key field, type Authorization.

6. In the Value field, type paste your copied token.

   If the token does not start with “Bearer”, add the word Bearer followed by a space to indicate the type of token being sent.

7. Begin making API calls.