Diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_invites_api/README.markdown	Sun Sep 13 11:05:19 2020 +0100
@@ -0,0 +1,113 @@
+---
+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
+```
\ No newline at end of file