Prosodical Thoughts

News, announcements and thoughts from the Prosody IM team

Great Invitations

by The Prosody Team
Translations available: [de] 

There are two kinds of servers on the XMPP network today: those with public registration, and those without.

The servers that support registration generally allow you to create accounts via the web, or using your XMPP client (XEP-0077). The problem is that this opens your server up to the world. Even when you add CAPTCHAs and other defences, even the most careful XMPP public server admin will at some point see spammers registering accounts on their server.

The alternative option is to disable registration, and provision all accounts manually. This works for a private server, but means extra effort and responsibilities of the admin. In many cases it also means that the admin is responsible for generating the user’s password and finding a way to securely send it to them somehow.

But wait! There is a third way! The concept of invite-only internet services has been around for a long time. When Google launched Gmail it was famously only possible to sign up through invitation. Today it has over 1.5 billion users! Maybe your aspirations as a Prosody admin are not so high, but there are some definite advantages to an invite-based registration flow:

  • Server admins can create account invites, and never need to generate or see another user’s password.
  • Invitation links naturally identify the server that they are from, so the user does not need to manually select a server in their client (a surprisingly common difficulty for people unfamiliar with the concept of federated messaging networks).
  • User-to-user invitations can be enabled by the admin, allowing for a more natural and trust-based growth than open registration.
  • Invited users can have their contact list already seeded with the person who invited them, removing yet another hurdle that first-time users usually have to deal with.
  • Abusive accounts (such as those sending spam) can be traced to an inviting user, and that user can be prevented from creating further invitations.

Experience with the invite-based registration flow we developed for Snikket has shown that invite links are a really easy way to get people signed up to a server without needing to enable open registration. So we decided to bring this to the broader XMPP ecosystem.

Screenshot of the Prosody invitation page

Screenshot of the new Prosody invitation page

Our goal was to keep as much of the simplicity of the Snikket registration flow as possible, while opening the possibility of working with other clients across as many platforms as possible. This is not as easy as you might think!

How it works

We broke clients down into three categories based on whether they support:

  • “Magic” installation link - right now this is only supported by some apps on the Google Play store (Conversations and yaxim). An issue has been filed with F-Droid to see if we can extend this handy feature to FOSS app stores too.
  • xmpp: URIs with invite tokens (currently known to be Conversations, yaxim and Siskin).
  • Manual account setup

The “magic link” feature provides the most seamless flow. The user follows the link to install the app, and the invite token is magically discovered by the app after it is installed. This means the user flow is short and smooth:

Diagram depicting the user flow for magic install links

The magic installation link flow

If this flow is not supported, the next preferred option is to for the user to open the invite URI using their chosen app. The difficulty is that the client must be installed first, or the browser won’t know how to handle the URI. That means diverting the user to the client download and installation, and then they have to go back to the invite page:

Diagram depicting the user flow for invite URI links

The invite URI flow

Finally, if the client doesn’t support invite URIs, the user is guided through registering their account online (Prosody will validate the invite token), and then all the user has to do is enter their credentials into the client after they install it:

Diagram depicting the user flow for manual registration

The manual registration flow

With these three flows, we can turn an invite link into a signed-in user no matter what platform and client combination they opt for.

Data about clients is collected in mod_register_apps, and is also configurable by server admins (who may want to recommend a specific set of apps that they want to support for use on their server).

How to set it up

All the modules are in our community repository and should work with Prosody 0.11 and trunk.

Take a look at the example configuration snippet in mod_invites to get started! And once you’re done, maybe add mod_invites_api to create yourself a bookmarkable URL that can generate a new account invite at the click of a button.

Much of this work is very new, so we appreciate feedback :)

And don’t forget, if you’re setting up a simple Prosody server for a small group and want functionality like this and more ready configured, take a look at Snikket.


There are many ways to build on top of this. We hope to see more clients implement token URIs, and maybe some smart folk can even figure out how to expand the “magic link” flow to more platforms. We also think the invites API allowing trusted third-parties to generate account invites for a server has some very interesting potential uses.

Meanwhile we’re looking forward to feedback, contributions, and hearing about those onboarding success stories :)



Prosody is a lightweight and flexible XMPP server designed with ease-of-use and extensibility in mind.

⚛️ Atom feed

Recent Posts