Client Authentication

All access to the lookup service REST API requires authentication. Clients authenticate using a username and password to obtain a time-limited access token, which is then included in subsequent API requests as a bearer token.

Authenticating a client

To authenticate, send an HTTP POST request to the /auth/login endpoint with a JSON body containing the client username and password:

curl -X POST http://educates-api.<ingress-domain>/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "<name>", "password": "<password>"}'

The username corresponds to the metadata.name of the ClientConfig resource, and the password corresponds to the spec.client.password field.

On success, the response will be an HTTP 200 with a JSON body:

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_at": 1706745600
}

The access_token is a JWT token that should be used in subsequent API requests. The token_type will always be Bearer. The expires_at field is the token expiration time expressed as seconds since the UNIX epoch.

The access token currently expires after 72 hours, however this default may change in future versions. Clients should not assume a fixed expiration period and should always be prepared to handle token expiry regardless of the expected lifetime.

If the request body is malformed or missing required fields, the response will be HTTP 400. If the credentials are incorrect, the response will be HTTP 401.

Note that the /login endpoint also exists but is deprecated. Clients should use /auth/login instead.

Using the access token

After obtaining an access token, include it in the Authorization header of subsequent API requests using the Bearer scheme:

curl -X GET -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://educates-api.<ingress-domain>/api/v1/workshops?tenant=<tenant-name>

If the token has expired or been revoked, the API will return HTTP 401. When this occurs, the client should re-authenticate by calling the /auth/login endpoint again to obtain a new token.

Verifying a token

To check whether a token is still valid without making an API call, send an HTTP GET request to the /auth/verify endpoint:

curl -X GET -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://educates-api.<ingress-domain>/auth/verify

If the token is valid, the response will be HTTP 200. If the token has expired or been revoked, the response will be HTTP 401.

Token revocation

An access token can be explicitly revoked by calling the /auth/logout endpoint:

curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://educates-api.<ingress-domain>/auth/logout

In addition to explicit revocation, access tokens are also invalidated in the following circumstances:

The token reaches its expiration time.
The ClientConfig resource for the client is deleted.
The ClientConfig resource is deleted and immediately recreated (even with the same name and password).
The lookup service is restarted.

A custom front-end portal using the lookup service should not assume that a previously obtained token will remain valid indefinitely. It should be designed to handle an HTTP 401 response at any time by re-authenticating and retrying the request.

Capturing the token in a script

When testing the REST API from the command line, a common pattern is to capture the access token in an environment variable for use in subsequent commands:

ACCESS_TOKEN=$(curl --silent -X POST \
  http://educates-api.<ingress-domain>/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "custom-portal", "password": "my-secret"}' \
  | jq -r -e .access_token) && echo $ACCESS_TOKEN

The token can then be referenced in subsequent curl commands using ${ACCESS_TOKEN}.