prosody-modules: mod_invites_api/README.markdown annotate

annotate mod_invites_api/README.markdown @ 4738:5aee8d86629a

mod_bookmarks2: Fix handling of nick and password elements This form of child retrieval fails when the stanza elements internally don't have an 'xmlns' attribute, which can happen sometimes for some reason, including when they have been constructed via the stanza builder API. When that is the case then the explicit namespace arguemnt does not match the nil value of the internal attribute. Calling `:get_child()` without the namespace argument does the right thing here, with both nil and the parent namespace as valid values for the internal attribute.

author	Kim Alvefur <zash@zash.se>
date	Wed, 03 Nov 2021 21:11:55 +0100
parents	4ec755c13e9b
children	027fb71ad509

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 rockspec:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	6 dependencies:
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	7 - mod_invites
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 Introduction
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	11 ============
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	12
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	13 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	14 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	15
4223 4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	16 - [mod_invites]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	17 - [mod_invites_adhoc]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	18 - [mod_invites_page]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	19 - [mod_invites_register]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	20 - [mod_invites_register_web]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	21 - [mod_register_apps]
4115 165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	22
4223 4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4115 diff changeset	23 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	24
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	25 Details
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	26 =======
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 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	29 using mod_invites.
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	30
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	31 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	32
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	33 Configuration
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
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	36 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	37
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	38 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	39 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	40
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	41 API usage
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	42 =========
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 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	45 it is for
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 $ 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	49 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	50
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	51 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	52
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	53 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	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 HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
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 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	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 $ 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	63 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	64
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	65 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	66 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	67 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	68
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	69 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	70 < 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	71 < 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	72 < Connection: Keep-Alive
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	73 < Access-Control-Allow-Origin: *
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	74 < 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	75 < 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	76 < 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	77 < Content-Length: 0
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	78 < 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	79 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	80
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	81 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	82 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	83 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	84 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	85 bookmark :)
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 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	88 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	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 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	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 Key management
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 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	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 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	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 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	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 HTwALnKL My test key
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 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	110
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	111 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP Matthew Wild <mwild1@gmail.com> parents: diff changeset	112 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	113 ```

Mercurial > prosody-modules

annotate mod_invites_api/README.markdown @ 4738:5aee8d86629a