prosody-modules
tip
mod_invites_api/README.md

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.md @ 6211:750d64c47ec6 draft default tip

Merge
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Tue, 18 Mar 2025 00:31:36 +0700
parent 5635:mod_invites_api/README.markdown@99c0e675b969
parent 6003:mod_invites_api/README.markdown@fe081789f7b5
comparison
equal deleted inserted replaced
6210:24316a399978 6211:750d64c47ec6
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 You can also create an api key for a specific user:
92
93 ```
94 prosodyctl mod_invites_api create user@example.com
95 ```
96
97 Key management
98 ==============
99
100 To list all the available commands:
101
102 ```
103 prosodyctl mod_invites_api help
104 ```
105
106 To get help on a specific command for example `create`:
107
108 ```
109 prosodyctl mod_invites_api help create
110 ```