[GH-ISSUE #427] "Invalid macaroon passed" with Matrix Integration

kerem commented

2026-02-25 23:42:00 +03:00

Owner

Originally created by @markusressel on GitHub (Sep 11, 2020).
Original GitHub issue: https://github.com/healthchecks/healthchecks/issues/427

Hi there, great project!

I am using the linuxserver/healthchecks docker container to run a self-hosted instance. While the website itself works great, I struggle to get the Matrix integration to work.

The documentation for this is really sparse, so I had a hard time finding out how to go about this. Here are the steps I took:

I ran

register_new_matrix_user -c /data/config/homeserver.yaml http://localhost:14892 -u healthchecksio -p mypass

inside the docker container of my matrix (synapse) instance to create a new (non-admin) user to be used by the healthchecks instance.

I retrieved the access_token for this bot my using a login request and observing the response:

curl -XPOST -d '{"type":"m.login.password", "user":"@healthchecksio:matrix.mydomain.com", "password":"mypass"}' "https://matrix.mydomain.com:8448/_matrix/client/r0/login"

I set the environment variables:
MATRIX_ACCESS_TOKEN: REALLY_LONG_STRING_OF_CHARACTERS_AND_NUMBERS
MATRIX_HOMESERVER: https://matrix.mydomain.com (not the real domain obviously)
MATRIX_USER_ID: @healthchecksio:matrix.mydomain.com

Then I restarted the healthchecks docker container, opened my project of choice and the integrations page, clicked on "Add Integration" of the Matrix line. There I was prompted to enter a room id, so I

Created a new room using my personal Matrix account (on my private synapse instance)
Invited the @healthchecksio:matrix.mydomain.com user
Opened the room settings -> advanced tab and copied the "Internal Room ID"

I pasted this room id into the healthchecks website field and clicked on "Save Integration".
Then I received this error:

Response from Matrix: Invalid macaroon passed.

I did a little bit of research, and according to the Matrix homeserver.yaml config the macaroon is:

# a secret which is used to sign access tokens. If none is specified,
# the registration_shared_secret is used, if one is given; otherwise,
# a secret key is derived from the signing key.

I tried to comment out the macaroon_secret_key: line, but the error has not changed. I do not understand why the macaroon is even needed for the healthchecks integration. I guess it has something to do with the way the access_token is created and validated?

Any help would be much appreciated.

Originally created by @markusressel on GitHub (Sep 11, 2020). Original GitHub issue: https://github.com/healthchecks/healthchecks/issues/427 Hi there, great project! I am using the [linuxserver/healthchecks](https://hub.docker.com/r/linuxserver/healthchecks) docker container to run a self-hosted instance. While the website itself works great, I struggle to get the Matrix integration to work. The documentation for this is really sparse, so I had a hard time finding out how to go about this. Here are the steps I took: I ran ``` register_new_matrix_user -c /data/config/homeserver.yaml http://localhost:14892 -u healthchecksio -p mypass ``` inside the docker container of my matrix (synapse) instance to create a new (non-admin) user to be used by the healthchecks instance. I retrieved the `access_token` for this bot my using a login request and observing the response: ``` curl -XPOST -d '{"type":"m.login.password", "user":"@healthchecksio:matrix.mydomain.com", "password":"mypass"}' "https://matrix.mydomain.com:8448/_matrix/client/r0/login" ``` I set the environment variables: `MATRIX_ACCESS_TOKEN`: `REALLY_LONG_STRING_OF_CHARACTERS_AND_NUMBERS` `MATRIX_HOMESERVER`: `https://matrix.mydomain.com` (not the real domain obviously) `MATRIX_USER_ID`: `@healthchecksio:matrix.mydomain.com` Then I restarted the healthchecks docker container, opened my project of choice and the integrations page, clicked on "Add Integration" of the Matrix line. There I was prompted to enter a room id, so I * Created a new room using my personal Matrix account (on my private synapse instance) * Invited the `@healthchecksio:matrix.mydomain.com` user * Opened the room settings -> advanced tab and copied the "Internal Room ID" I pasted this room id into the healthchecks website field and clicked on "Save Integration". **Then I received this error:** ``` Response from Matrix: Invalid macaroon passed. ``` I did a little bit of research, and according to the Matrix `homeserver.yaml` config the macaroon is: ``` # a secret which is used to sign access tokens. If none is specified, # the registration_shared_secret is used, if one is given; otherwise, # a secret key is derived from the signing key. ``` I tried to comment out the `macaroon_secret_key:` line, but the error has not changed. I do not understand why the macaroon is even needed for the healthchecks integration. I guess it has something to do with the way the `access_token` is created and validated? Any help would be much appreciated.

kerem closed this issue

2026-02-25 23:42:01 +03:00

kerem commented

2026-02-25 23:42:01 +03:00

Author

Owner

@cuu508 commented on GitHub (Sep 18, 2020):

Hi @markusressel, thank you for the detailed report tracing your steps!

Can you check if the access token works if you try to join the room manually, using curl?

https://www.matrix.org/docs/guides/client-server-api#joining-a-room-via-an-alias

(that's more or less what Healthchecks does behind the scenes when you click "Save Integration")

@cuu508 commented on GitHub (Sep 18, 2020): Hi @markusressel, thank you for the detailed report tracing your steps! Can you check if the access token works if you try to join the room manually, using curl? https://www.matrix.org/docs/guides/client-server-api#joining-a-room-via-an-alias (that's more or less what Healthchecks does [behind the scenes](https://github.com/healthchecks/healthchecks/blob/master/hc/front/forms.py#L224) when you click "Save Integration")

kerem commented

2026-02-25 23:42:01 +03:00

Author

Owner

@markusressel commented on GitHub (Sep 20, 2020):

@cuu508 Thx for the response.

I am not sure if I need to login before using this curl command, but I get the same error.
Using this (redacted) command:

curl -X POST \
  'https://matrix.mydomain.de:8448/_matrix/client/r0/join/!RMmFZAZLAxdfxNvksL:matrix.mydomain.de?access_token=TOKEN' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "room_id": "!RMmFZAZLAxdfxNvksL:matrix.mydomain.de"
}'

I get this response:

{
  "errcode": "M_UNKNOWN_TOKEN",
  "error": "Invalid macaroon passed.",
  "soft_logout": false
}

@markusressel commented on GitHub (Sep 20, 2020): @cuu508 Thx for the response. I am not sure if I need to login before using this curl command, but I get the same error. Using this (redacted) command: ``` curl -X POST \ 'https://matrix.mydomain.de:8448/_matrix/client/r0/join/!RMmFZAZLAxdfxNvksL:matrix.mydomain.de?access_token=TOKEN' \ -H 'Content-Type: application/json; charset=utf-8' \ -d '{ "room_id": "!RMmFZAZLAxdfxNvksL:matrix.mydomain.de" }' ``` I get this response: ``` { "errcode": "M_UNKNOWN_TOKEN", "error": "Invalid macaroon passed.", "soft_logout": false } ```

kerem commented

2026-02-25 23:42:01 +03:00

Author

Owner

@cuu508 commented on GitHub (Sep 21, 2020):

Unfortunately I don't have experience with running my own Matrix instance, and cannot help on that front.

Here's what I did for setting up the credentials for the hosted service (IIRC, was a while ago):

I registered the bot user using web client (riot.im). I set up the account (user picture etc.) as a normal user from within the browser.
I used the login API call to retrieve bot user's access token
I didn't use the web interface from then on

I would assume that the register and login calls give out similar access tokens, but don't know for sure. I suppose this would be one thing to try: run the login API call, grab the returned access token and try joining a room using that access token.

@cuu508 commented on GitHub (Sep 21, 2020): Unfortunately I don't have experience with running my own Matrix instance, and cannot help on that front. Here's what I did for setting up the credentials for the hosted service (IIRC, was a while ago): * I registered the bot user using web client (riot.im). I set up the account (user picture etc.) as a normal user from within the browser. * I used the [login API call](https://www.matrix.org/docs/guides/client-server-api#login) to retrieve bot user's access token * I didn't use the web interface from then on I would assume that the `register` and `login` calls give out similar access tokens, but don't know for sure. I suppose this would be one thing to try: run the login API call, grab the returned access token and try joining a room using that access token.

kerem commented

2026-02-25 23:42:01 +03:00

Author

Owner

@markusressel commented on GitHub (Sep 22, 2020):

Thats pretty much what I did. As I wrote in the first post, I used the login API to get the access token, after I had created this user using the command line utility provided by matrix (synapse).

I did not try to login to the bot account using some normal client, so it may be that this is necessary for full account activation.

Also, I am still not sure if "bot user" refers to some special kind of user, or simply a normal user that is just used by the healthchecks kinda like a bot. Reading your instructions it seems like it is a normal user like every other, however the wording is confusing to me, because afaik "real" Matrix Bots create their users on their own.

I am also unsure about the encryption support of the healthchecks bot implementation. When creating a new room within Element I've been offered to disable/enable encryption, as well as allowing public access to this room. I have tried to disable encryption, but the result is the same. Since I get the error from the curl command I am pretty sure though that this is not an error in healthchecks, but my synapse configuration. I will investigate this further asap.

@markusressel commented on GitHub (Sep 22, 2020): Thats pretty much what I did. As I wrote in the first post, I used the login API to get the access token, after I had created this user using the command line utility provided by matrix (synapse). I did not try to login to the bot account using some normal client, so it may be that this is necessary for full account activation. Also, I am still not sure if "bot user" refers to some special kind of user, or simply a normal user that is just used by the healthchecks *kinda like a bot*. Reading your instructions it seems like it is a normal user like every other, however the wording is confusing to me, because afaik "real" Matrix Bots create their users on their own. I am also unsure about the encryption support of the healthchecks bot implementation. When creating a new room within Element I've been offered to disable/enable encryption, as well as allowing public access to this room. I have tried to disable encryption, but the result is the same. Since I get the error from the curl command I am pretty sure though that this is not an error in healthchecks, but my synapse configuration. I will investigate this further asap.

kerem commented

2026-02-25 23:42:01 +03:00

Author

Owner

@cuu508 commented on GitHub (Sep 29, 2020):

@markusressel did you find a solution for this issue (in the synapse configuration or otherwise)?

@cuu508 commented on GitHub (Sep 29, 2020): @markusressel did you find a solution for this issue (in the synapse configuration or otherwise)?

kerem commented

2026-02-25 23:42:01 +03:00

Author

Owner

@markusressel commented on GitHub (Sep 29, 2020):

I have not had the time to investigate this yet. Bare with me please 😄
EDIT:
Not yet sure what the culprit is, but this suggests something about the token is wrong. Either it is not passed correctly to the Matrix server, or the server rejects it. Since the curl also fails I tend to think its the latter.

@markusressel commented on GitHub (Sep 29, 2020): I have not had the time to investigate this yet. Bare with me please :smile: EDIT: Not yet sure what the culprit is, but [this](https://github.com/matrix-org/matrix-appservice-irc/issues/942#issuecomment-583906337) suggests something about the token is wrong. Either it is not passed correctly to the Matrix server, or the server rejects it. Since the curl also fails I tend to think its the latter.

kerem commented

2026-02-25 23:42:01 +03:00

Author

Owner

@P-Takenaka commented on GitHub (Mar 12, 2021):

I had the same error. I solved the issue by not enclosing my matrix environment variables with quotes in my docker compose file, as in

      - MATRIX_HOMESERVER=https://matrix.example.com
      - MATRIX_ACCESS_TOKEN=AccessToken
      - MATRIX_USER_ID=@user:domain

instead of

      - MATRIX_HOMESERVER="https://matrix.example.com"
      - MATRIX_ACCESS_TOKEN="AccessToken"
      - MATRIX_USER_ID="@user:domain"

@P-Takenaka commented on GitHub (Mar 12, 2021): I had the same error. I solved the issue by not enclosing my matrix environment variables with quotes in my docker compose file, as in ``` - MATRIX_HOMESERVER=https://matrix.example.com - MATRIX_ACCESS_TOKEN=AccessToken - MATRIX_USER_ID=@user:domain ``` instead of ``` - MATRIX_HOMESERVER="https://matrix.example.com" - MATRIX_ACCESS_TOKEN="AccessToken" - MATRIX_USER_ID="@user:domain" ```

Rows
Columns

[GH-ISSUE #427] "Invalid macaroon passed" with Matrix Integration #317