prosody-modules: mod_invites_api/README.markdown annotate

annotate mod_invites_api/README.markdown @ 4832:bfd4af4caddc

mod_password_policy: Support for additional policies provided by other modules E.g. check a password contains an uppercase character: module:provides("password-policy", { name = "contains_uppercase"; check_password = function (password, policy) return (policy ~= true) or (not not password:match("%u")); end; }) Config: password_policy = { contains_uppercase = true; }

author	Matthew Wild <mwild1@gmail.com>
date	Wed, 22 Dec 2021 14:48:46 +0000
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 @ 4832:bfd4af4caddc