Services
Any service can integrate the Lissi Agent API via HTTP requests.
Authentication
To authenticate clients the Lissi Agent expects up to two headers:
authorization
header including a bearer tokenx-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>'
In return the token endpoint provides two tokens:
Access Token (expires after 10 minutes by default)
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>'
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>'
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>'