Any service can integrate the Lissi Agent API via HTTP requests.

Authentication

To authenticate clients the Lissi Agent expects up to two headers:

  1. authorization header including a bearer token

  2. x-tenant-id header including a tenant ID (only required for tenant endpoints but not admin endpoints)

authorization Header

The token endpoint should be used to retrieve an access token based on the login credentials of a user:

curl --location --request POST 'https://<DOMAIN>/auth/realms/lissi-cloud/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=lissi-agent-client' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'username=<USER>' \
  --data-urlencode 'password=<PASSWORD>'
CODE

In return the token endpoint provides two tokens:

  1. Access Token (expires after 10 minutes by default)

  2. Refresh Token (expires after 30 minutes by default)

The access token should be sent with every request in the authorization header. By default, the access token expires after 10 minutes (independent if it is used or not). Afterward, a new access token can be requested using the token endpoint and username and password or by using the token endpoint in combination with the refresh token:

curl --location --request POST 'https://<DOMAIN>/auth/realms/lissi-cloud/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=lissi-agent-client' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=<REFRESH_TOKEN>'
CODE

x-tenant-id Header

The x-tenant-id header is required for all non-admin endpoints. The following admin endpoints do NOT require the x-tenant-id header:

  • POST ​/ctrl​/api​/v1.0​/tenants​/create

  • POST ​/ctrl​/api​/v1.0​/tenants​/{id}​/update

  • POST ​/ctrl​/api​/v1.0​/tenants​/{id}​/delete

Suggested Strategy for Access Tokens

To optimize for performance, access tokens should only be refreshed just before they expire. A service can check before each HTTP call to the Lissi Agent if it has a non-expired access token in the cache. If this is the case the application should use this access token. In case the service doesn't have a non-expired access token yet OR if the access token is about to expire during the next 60 seconds it can retrieve an access token based on the login credentials of a user as outlined above.

Sample Requests

Request with authorization and x-tenant-id Headers

curl --location --request GET 'https://<DOMAIN>/ctrl/api/v1.0/did' \
  --header 'x-tenant-id: <TENANT_ID>' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'
CODE

Request with authorization Header Only

curl --location --request POST 'https://<DOMAIN>/ctrl/api/v1.0/tenants/create?label=Test Agent&id=test_agent' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'
CODE