Tokens and secrets
Everything that proves who is calling is a secret of 256 random bits behind a prefix that says what it is. The prefix is for people and for secret scanners: a token pasted in a public repository is recognised by it. It adds no strength; the strength is in the random part.
| Secret | Looks like | Lives | Used for |
|---|---|---|---|
| Bot token | moymo_bot_<app id>.<43 characters> | Until you reset it | Authorization: Bot <token> on the App API |
| Client secret | moymo_cs_<43 characters> | Until you delete it | Proving your server is your application at the token endpoint |
| Access token | moymo_at_<43 characters> | 1 hour | Authorization: Bearer <token> on behalf of a member |
| Refresh token | moymo_rt_<43 characters> | 30 days, used once | Getting a new access token |
How they are kept
- A secret is shown once, when it is made, and Moymo keeps only the SHA-256 hash of it. A leak of Moymo's database is therefore not a leak of your tokens, and nobody at Moymo can tell you what yours is.
- A bot token carries the id of its application before the dot, so a token found somewhere says whose it is. That is a convenience for you and for support; it is not what authenticates.
- The portal shows the last four characters of a secret after the first time (
moymo_cs_...k2Zp) so you can tell them apart.
Rotating
| Bot token | Reset token on the Bot tab makes a new one. The old one stops working at the same moment; the bot is offline until its code has the new one. |
| Client secret | Add a secret, deploy it, then Delete the old one. Or Reset all, which deletes every secret and shows one new one. Up to three can exist at once. |
| Access and refresh tokens | A member can take an authorisation back in Settings > Connected apps, which ends it and every token it made. Your app can revoke a token itself at the revoke endpoint. Each refresh token works once: using it gives a new pair, and using it again is refused. |
Keeping them safe
Treat a token like a password
Anyone with a bot token can do whatever the bot can do in every server it is in. Anyone with a client secret can pretend to be your application.
- Keep secrets in environment variables or a secret manager, not in code and not in a repository. If one is committed by mistake, reset it first, then clean the history.
- Never put a client secret or a bot token in a web page, a mobile app or anything a user can download. Apps that run on a user's device use PKCE and have no secret.
- A token is a credential for Moymo's API only; it is not an end-to-end key. Moymo for Windows can seal the text of a channel so that Moymo's server cannot read it; a bot is a participant on the server side and cannot read sealed text either.
- Moymo cannot redact a secret you post in a message or an issue. If it leaks, reset it.
What a token cannot do
A bot token and an access token work on /api/app/v1 and nowhere else. They cannot reach a member's own endpoints (settings, library, messages to friends), cannot change a password and cannot sign in to Moymo. An access token is the member only for what the member allowed: the scopes on it.