author | Kim Alvefur <zash@zash.se> |
Sat, 06 Apr 2024 17:55:23 +0200 | |
changeset 5884 | eb1c524a5150 |
parent 5145 | 027fb71ad509 |
permissions | -rw-r--r-- |
4119
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 |
|
4227
4ec755c13e9b
mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents:
4119
diff
changeset
|
13 |
- [mod_invites] |
4ec755c13e9b
mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents:
4119
diff
changeset
|
14 |
- [mod_invites_adhoc] |
4ec755c13e9b
mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents:
4119
diff
changeset
|
15 |
- [mod_invites_page] |
4ec755c13e9b
mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents:
4119
diff
changeset
|
16 |
- [mod_invites_register] |
4ec755c13e9b
mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents:
4119
diff
changeset
|
17 |
- [mod_invites_register_web] |
4ec755c13e9b
mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents:
4119
diff
changeset
|
18 |
- [mod_register_apps] |
4119
165ade4ce97b
mod_invites_api: New module to create new invites over HTTP
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
19 |
|
4227
4ec755c13e9b
mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents:
4119
diff
changeset
|
20 |
For details and a full overview, start with the [mod_invites] documentation. |
4119
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 |
``` |