Basic auth do not work with api. Missing documentation for api key.

[jorgen-k]

Version:

• listmonk: 4.0.1
• OS: docker (provided docker_compose)

Description of the bug and steps to reproduce:

I’ve spent several hours trying to successfully authenticate API calls with a new, standard Docker install of Listmonk. Despite following the API documentation, it was unclear how to use the API key effectively. Here’s the detailed issue:

1. Basic Auth Expectation:
   After creating a user, I initially tried basic auth as suggested in common API setups. This returned a 403 error. There’s no mention in the documentation that basic auth is not supported or that an API key is required instead. Instead the documentation clearly gives examples that do not work.

curl -u "admin:password" http://localhost:9000/api/lists

2. API Key Usage Confusion:
   After discovering via community discussions that an API key was possible from 4.0, I created a new user and generated an API key. However, the documentation does not provide clear guidance on how to create or use this key, leading to many trial-and-error attempts to find the correct header format, like standardized ways with Bearer or x-api-key.

3. Working Solution After Trial and Error:
   After much experimentation, I finally got the correct format to work. However, more standard formats typically used in other APIs were unsuccessful. Not only did I have to include the specific API user name, but also the prefix "token" along with a specific syntax that was unclear from the documentation.

curl -H "Authorization: token api:MOCK_TOKEN_sdfjkhsdfhjksdfn" http://localhost:9000/api/lists

I consider this a bug, it is probably not intentional.

Suggested Improvements:

• Clear Documentation on API Key Usage: It would be helpful if the documentation explicitly mentioned the need for an API key and provided clear working examples of the required syntax.
• Consistent and Standard Header Format: Using a format more consistent with industry standards would improve usability.
• Backwards compatibility: as promised in other threads it would be nice with backwards compatibility

Including these updates in the documentation would help new users avoid similar difficulties in getting started with API calls. Thank you for considering these improvements.

This issue partly for documenting my find to help others not need to struggle for hours.

[knadh]

I've updated the documentation and changed curl -u username:passwordtocurl -u 'api_username:access_token'`. BasicAuth works for new API access, but instead of "password", we just have send the auto-generated token.

[jorgen-k]

I can confirm it works also with -u api_username:access_token, apart from the token header. Thanks for the swift response!

[Virock]

Can someone please direct me on how I can obtain an API username and access token? @knadh Your message says the token is auto-generated. Where do I find it?

[jorgen-k]

Users -> Users. Create a new user of type API and you will see the api-key once only, so do not forget to copy it.