Skip to main content
Every provider makes you authenticate differently. Slack wants two tokens pasted, Google wants a browser round trip, WhatsApp wants a QR code scanned by your phone. You should not have to know which one you are in for before you can connect something.

​
What karmax integrations tells you

STATE is the result of a real call to the provider, not a check that a config field is non-empty — which is exactly the state an expired token is also in. CREDENTIALS FROM answers the question you will eventually have: I set that key in the yaml, so why is it using something else?
KARMAX re-checks every 30 minutes on its own. The point is that a dead credential becomes visible before something depends on it, rather than surfacing as a loop failing at 4am.

​
Where credentials live

Three places, in this order — the first one that has a value wins, per value:
1

KARMAX's own store

What karmax login writes. It wins because logging in is an act you just performed, and it should not be silently overridden by a setting somebody wrote months ago.
2

karmax.yaml

A token: or a settings: entry, with ${ENV} interpolated. This is the right place for a container install where you manage config as a file.
3

The environment

KARMAX_<INTEGRATION>_<FIELD> — so Slack’s bot token is KARMAX_SLACK_BOT_TOKEN.
Merging is per value, not wholesale: a client id in karmax.yaml survives a login that only obtains a token.

​
The four ways of connecting

KARMAX prompts for each field the integration declares, without echoing anything secret, then calls the provider before saving. A key that does not work fails while you still have the page open, rather than hours later inside a loop.
KARMAX opens a listener on 127.0.0.1, opens your browser, and exchanges the code when the provider redirects back. Loopback rather than a hosted redirect, because KARMAX runs behind your router and there is no public URL to send anyone to. Refresh tokens are stored and used automatically.
wacli holds a WhatsApp pairing and gws holds a Google session, each in its own store. KARMAX cannot log those in and does not keep a second copy of a secret it does not own — it checks, and tells you the exact command:
Some integrations need no credentials. karmax login says so and exits rather than inventing a question.

​
Several accounts on one provider

A work GitHub and a personal one, both connected at once:
The primary account keeps the plain tool names (github.issues); each named account gets its own (github.issues@work), so the agent acts as the identity you meant rather than whichever token loaded first.

​
What is available

Instagram is unofficial. It drives Instagram’s private API by impersonating the mobile app. That is against their terms, accounts get restricted for it, and the credential is a real password rather than a revocable token. It stays off until you set KARMAX_ENABLE_INSTAGRAM=true, is read-only, and never polls. Enable it only if you accept that the account may be restricted.