File

---
labels:
- 'Stage-Beta'
summary: 'Authenticated HTTP API to create invites'
rockspec:
  dependencies:
  - mod_invites
...

Introduction
============

This module is part of the suite of modules that implement invite-based
account registration for Prosody. The other modules are:

- mod_invites
- mod_invites_adhoc
- mod_invites_page
- mod_invites_register
- mod_invites_register_web
- mod_register_apps

For details and a full overview, start with the mod_invites documentation.

Details
=======

mod_invites_api provides an authenticated HTTP API to create invites
using mod_invites.

You can use the command-line to create and manage API keys.

Configuration
=============

There are no specific configuration options for this module.

All the usual [HTTP configuration options](https://prosody.im/doc/http)
can be used to configure this module.

API usage
=========

Step 1: Create an API key, with an optional name to help you remember what
it is for

```
$ prosodyctl mod_invites_api create example.com "My test key"
```

**Tip:** Remember to put quotes around your key name if it contains spaces.

The command will print out a key:

```
HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
```

Step 2: Make a HTTP request to Prosody, containing the key

```
$ curl -v https://example.com:5281/invites_api?key=HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
```

Prosody will respond with a HTTP status code "201 Created" to indicate
creation of the invite, and per HTTP's usual rules, the URL of the created
invite page will be in the `Location` header:

```
< HTTP/1.1 201 Created
< Access-Control-Max-Age: 7200
< Connection: Keep-Alive
< Access-Control-Allow-Origin: *
< Date: Sun, 13 Sep 2020 09:50:19 GMT
< Access-Control-Allow-Headers: Content-Type
< Access-Control-Allow-Methods: OPTIONS, GET
< Content-Length: 0
< Location: https://example.com/invite?c-vhJjyB5Pb4HpAf
```

Sometimes for convenience, you may want to just visit the URL in the
browser. Append `&redirect=true` to the URL, and instead Prosody will
return a `303 See Other` response code, which will tell the browser to
redirect straight to the newly-created invite. This is super handy in a
bookmark :)

If using the API programmatically, it is recommended to put the key in
the `Authorization` header if possible. This is quite simple:

```
Authorization: Bearer HTwALnKL/73UUylA-2ZJbu9x1XMATuIbjWpip8ow1
```

Key management
==============

At any time you can view authorized keys using:

```
prosodyctl mod_invites_api list example.com
```

This will list out the id of each key, and the name if set:

```
HTwALnKL	My test key
```

You can revoke a key by passing this key id to the 'delete` sub-command:

```
prosodyctl mod_invites_api delete example.com HTwALnKL
```