Mercurial > prosody-modules

annotate mod_invites_api/README.markdown @ 5293:f60287bba62c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_admin_api: Add roles to user schema in openapi
author Kim Alvefur <zash@zash.se>
date Thu, 30 Mar 2023 12:06:18 +0200
parents 027fb71ad509
children
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 ...
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 Introduction
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 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
11 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
12
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4115
diff changeset
13 - [mod_invites]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4115
diff changeset
14 - [mod_invites_adhoc]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4115
diff changeset
15 - [mod_invites_page]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4115
diff changeset
16 - [mod_invites_register]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4115
diff changeset
17 - [mod_invites_register_web]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4115
diff changeset
18 - [mod_register_apps]
4115
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4115
diff changeset
20 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
21
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 Details
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 =======
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 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
26 using mod_invites.
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 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
29
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 Configuration
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 =============
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 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
34
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 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
36 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
37
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 API usage
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 =========
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 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
42 it is for
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 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 $ 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
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 **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
49
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 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
51
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 HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
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 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
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 $ 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
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 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
63 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
64 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
65
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 < 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
68 < 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
69 < Connection: Keep-Alive
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 < Access-Control-Allow-Origin: *
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 < 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
72 < 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
73 < 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
74 < Content-Length: 0
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 < 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
76 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 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
79 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
80 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
81 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
82 bookmark :)
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
83
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
84 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
85 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
86
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87 ```
165ade4ce97b mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
88 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
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 Key management
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 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
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 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
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 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
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 HTwALnKL My test key
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 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
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 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
110 ```