Software /
code /
prosody-modules
Annotate
mod_invites_api/README.markdown @ 5042:166fd192f39c
mod_sasl2: Move <inline/> into <authentication>
This is a small change we've agreed upon in the upcoming version of the XEP.
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Wed, 21 Sep 2022 10:25:34 +0100 |
parent | 4223:4ec755c13e9b |
child | 5141: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 ``` |