view mod_invites_api/README.markdown @ 4690:82dabfffaddf

mod_muc_require_tos: Add this new module
author Emmanuel Gil Peyrot <>
date Thu, 16 Sep 2021 20:41:14 +0200
parents 4ec755c13e9b
line wrap: on
line source

- 'Stage-Beta'
summary: 'Authenticated HTTP API to create invites'
  - mod_invites


This module is part of the suite of modules that implement invite-based
account registration for Prosody. The other modules are:

- [mod_invites]
- [mod_invites_adhoc]
- [mod_invites_page]
- [mod_invites_register]
- [mod_invites_register_web]
- [mod_register_apps]

For details and a full overview, start with the [mod_invites] documentation.


mod_invites_api provides an authenticated HTTP API to create invites
using mod_invites.

You can use the command-line to create and manage API keys.


There are no specific configuration options for this module.

All the usual [HTTP configuration options](
can be used to configure this module.

API usage

Step 1: Create an API key, with an optional name to help you remember what
it is for

$ prosodyctl mod_invites_api create "My test key"

**Tip:** Remember to put quotes around your key name if it contains spaces.

The command will print out a key:


Step 2: Make a HTTP request to Prosody, containing the key

$ curl -v

Prosody will respond with a HTTP status code "201 Created" to indicate
creation of the invite, and per HTTP's usual rules, the URL of the created
invite page will be in the `Location` header:

< HTTP/1.1 201 Created
< Access-Control-Max-Age: 7200
< Connection: Keep-Alive
< Access-Control-Allow-Origin: *
< Date: Sun, 13 Sep 2020 09:50:19 GMT
< Access-Control-Allow-Headers: Content-Type
< Access-Control-Allow-Methods: OPTIONS, GET
< Content-Length: 0
< Location:

Sometimes for convenience, you may want to just visit the URL in the
browser. Append `&redirect=true` to the URL, and instead Prosody will
return a `303 See Other` response code, which will tell the browser to
redirect straight to the newly-created invite. This is super handy in a
bookmark :)

If using the API programmatically, it is recommended to put the key in
the `Authorization` header if possible. This is quite simple:

Authorization: Bearer HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1

Key management

At any time you can view authorized keys using:

prosodyctl mod_invites_api list

This will list out the id of each key, and the name if set:

HTwALnKL	My test key

You can revoke a key by passing this key id to the 'delete` sub-command:

prosodyctl mod_invites_api delete HTwALnKL