Lab 01 - Log in to the REST API

What you will learn

The four different ways to log in to the Domino REST API.

Before you begin

• You have completed Lab 0 - Overview.
• You have a Domino server running with REST API active.
• You have downloaded the KEEP tool: keep for Mac/Linux or keep.cmd for Windows.

Procedure

Set permissions

The database KeepConfig.nsf uses the group LocalKeepAdmins for access control. You need to create this group in your Domino directory and assign your user account to this group.

Use your own credentials

The steps below use "KEEP Admin" and "passw0rd" as credentials. Replace those with the admin user on your Domino server.

Log in to the REST API

Log in using the command line

Run the following curl command to log in.

curl --location --request POST "http://localhost:8880/api/v1/auth" \
   --header 'Content-Type: application/json' \
   --data-raw '{"username" : "KEEP Admin", "password" : "passw0rd"}'

All on one line

The curl command above is one line. To enhance readability, it is broken into multiple lines using the "continuation character". On macOS/Linux that is \. On Windows, that is ^.

Alternatively, use the keep login command.

On successful login, you receive a JSON response containing a token that you can verify on jwt.io.

Log in using Swagger UI

1. Access the second tile on the Domino REST API landing page.

   

2. Make sure you have the correct port, protocol, and host. For a local installation, this is the set-up:

   Variable	required value
   port	8880
   protocol	http
   host	localhost

   

3. Scroll down to authentication and expand authLogin. Fill in the username and password, and click Execute.

   

4. Copy the generated bearer token into the following form, which opens after clicking button.

   

5. Click Authorize.

Log in to Admin UI

1. Access the first tile on the Domino REST API landing page.

   

2. Fill in your username and password, and click LOGIN.

   

   A successful login shows the Admin UI.

   

Log in using Postman

Note

Make sure you have downloaded the Postman collection and environment, and have imported them into Postman.

• Start Postman, open the Lab1 folder, and execute the first entry labeled Login.

  A successful login shows the bearer token and 4 passed tests.

  

How to verify

For the methods that return a bearer token, copy the token and verify it in the JWT Token checker. Take note that each token has a different start time and end time.

Things to explore

• Domino REST API documentation

• Discord discussion

• Call the /api endpoint using curl.

• Check the different OpenAPI collections in the Swagger UI.
• Check what happens when invalid credentials are provided.
• Access an endpoint, such as /api/v1/scopes, then the logout endpoint and try again.

Next step

Proceed to Lab 02 - Quick config.