Mercurial > prosody-modules

annotate mod_invites_api/README.markdown @ 4362:116c88c28532

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_admin_api: restructure group-related info in API - Return the members of the group right in the get_group_by_id call. This is an O(1) of extra work. - Remove the groups attribute from get_user_by_name as that is O(n) of work and rarely immediately needed. The replacement for the group membership information in the user is for now to use the group API and iterate; future work may fix that.
author Jonas Schäfer <jonas@wielicki.name>
date Wed, 20 Jan 2021 15:30:29 +0100
parents 4ec755c13e9b
children 027fb71ad509
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 ```