Mercurial > prosody-modules

comparison mod_invites_api/README.md @ 5975:fe081789f7b5

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