mod_sasl2: Move <inline/> into <authentication>
This is a small change we've agreed upon in the upcoming version of the XEP.
---
labels:
- 'Stage-Beta'
summary: 'Authenticated HTTP API to create invites'
rockspec:
dependencies:
- mod_invites
...
Introduction
============
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.
Details
=======
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.
Configuration
=============
There are no specific configuration options for this module.
All the usual [HTTP configuration options](https://prosody.im/doc/http)
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 example.com "My test key"
```
**Tip:** Remember to put quotes around your key name if it contains spaces.
The command will print out a key:
```
HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
```
Step 2: Make a HTTP request to Prosody, containing the key
```
$ curl -v https://example.com:5281/invites_api?key=HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
```
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: https://example.com/invite?c-vhJjyB5Pb4HpAf
```
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 example.com
```
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 example.com HTwALnKL
```