Skip to content

Lab 01 - Login to the REST API

Duration 10 min

What you will learn

Four ways to login to the REST API

Prerequisites

  • Lab 0 completed

  • Domino with REST running

  • downloaded keep or keep.cmd from here

Steps in logging in to the REST API

Set permissions

The database KeepConfig.nsf uses the group LocalKeepAdmins for access control. So create that group in your Domino directory and assign your user to it.

Use your own credentials

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

1. Login using the command line

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 command above is one line. To make it more readable it is broken into multiple lines using the "continuation character". On macOS/Linux that is \, on Windows ^.

Alternative type keep login

You will, on successful login, receive a JSON response we can verify on jwt.io.

Successful local login

2. Login using the OpenAPI UI

The second tile on the landing page provides access to the openAPI UI (a.k.a Swagger).

Access to Swagger

Check 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

Access to Swagger

Scroll down to authentication, expand authLogin, and click try it out. Fill in username and password.

Access to Swagger

The resulting bearer needs to be copied into form behind the button. Access to Swagger.

Access to Swagger

3. Login Admin UI

Admin Login

A successful login shows the Admin UI.

Admin UI

4. Login using Postman

  • Download Import the Postman collection and environment

  • Open the Lab1 folder, execute the first entry labeled "Login"

The successful login shows the bearer token and 4 passed tests

Postman login

How to check

  • All methods return the bearer token. Copy the token and paste it in the JWT Token checker

  • Each token has a different start/end time

Things to explore

  • Official 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.