prosody-modules: mod_invites_api/README.markdown annotate

annotate mod_invites_api/README.markdown @ 5668:ecfd7aece33b

mod_measure_modules: Report module statuses via OpenMetrics Someone in the chat asked about a health check endpoint, which reminded me of mod_http_status, which provides access to module statuses with full details. After that, this idea came about, which seems natural. As noted in the README, it could be used to monitor that critical modules are in fact loaded correctly. As more modules use the status API, the more useful this module and mod_http_status becomes.

author	Kim Alvefur <zash@zash.se>
date	Fri, 06 Oct 2023 18:34:39 +0200
parents	027fb71ad509
children

rev	line source
4115 165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	1 ---
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	2 labels:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	3 - 'Stage-Beta'
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	4 summary: 'Authenticated HTTP API to create invites'
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	5 ...
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	6
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	7 Introduction
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	8 ============
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	9
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	10 This module is part of the suite of modules that implement invite-based
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	11 account registration for Prosody. The other modules are:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	12
4223 4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	13 - [mod_invites]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	14 - [mod_invites_adhoc]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	15 - [mod_invites_page]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	16 - [mod_invites_register]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	17 - [mod_invites_register_web]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	18 - [mod_register_apps]
4115 165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	19
4223 4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	20 For details and a full overview, start with the [mod_invites] documentation.
4115 165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	21
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	22 Details
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	23 =======
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	24
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	25 mod_invites_api provides an authenticated HTTP API to create invites
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	26 using mod_invites.
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	27
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	28 You can use the command-line to create and manage API keys.
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	29
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	30 Configuration
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	31 =============
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	32
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	33 There are no specific configuration options for this module.
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	34
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	35 All the usual [HTTP configuration options](https://prosody.im/doc/http)
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	36 can be used to configure this module.
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	37
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	38 API usage
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	39 =========
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	40
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	41 Step 1: Create an API key, with an optional name to help you remember what
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	42 it is for
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	43
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	44 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	45 $ prosodyctl mod_invites_api create example.com "My test key"
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	46 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	47
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	48 Tip: Remember to put quotes around your key name if it contains spaces.
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	49
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	50 The command will print out a key:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	51
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	52 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	53 HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	54 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	55
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	56 Step 2: Make a HTTP request to Prosody, containing the key
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	57
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	58 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	59 $ curl -v https://example.com:5281/invites_api?key=HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	60 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	61
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	62 Prosody will respond with a HTTP status code "201 Created" to indicate
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	63 creation of the invite, and per HTTP's usual rules, the URL of the created
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	64 invite page will be in the `Location` header:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	65
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	66 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	67 < HTTP/1.1 201 Created
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	68 < Access-Control-Max-Age: 7200
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	69 < Connection: Keep-Alive
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	70 < Access-Control-Allow-Origin: *
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	71 < Date: Sun, 13 Sep 2020 09:50:19 GMT
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	72 < Access-Control-Allow-Headers: Content-Type
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	73 < Access-Control-Allow-Methods: OPTIONS, GET
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	74 < Content-Length: 0
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	75 < Location: https://example.com/invite?c-vhJjyB5Pb4HpAf
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	76 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	77
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	78 Sometimes for convenience, you may want to just visit the URL in the
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	79 browser. Append `&redirect=true` to the URL, and instead Prosody will
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	80 return a `303 See Other` response code, which will tell the browser to
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	81 redirect straight to the newly-created invite. This is super handy in a
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	82 bookmark :)
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	83
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	84 If using the API programmatically, it is recommended to put the key in
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	85 the `Authorization` header if possible. This is quite simple:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	86
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	87 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	88 Authorization: Bearer HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	89 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	90
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	91 Key management
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	92 ==============
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	93
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	94 At any time you can view authorized keys using:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	95
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	96 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	97 prosodyctl mod_invites_api list example.com
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	98 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	99
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	100 This will list out the id of each key, and the name if set:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	101
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	102 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	103 HTwALnKL My test key
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	104 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	105
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	106 You can revoke a key by passing this key id to the 'delete` sub-command:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	107
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	108 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	109 prosodyctl mod_invites_api delete example.com HTwALnKL
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	110 ```

Mercurial > prosody-modules

annotate mod_invites_api/README.markdown @ 5668:ecfd7aece33b