prosody-modules
165ade4ce97b
mod_invites_api/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_invites_api/README.markdown @ 4115:165ade4ce97b

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