Simple ejabberd Rest API Configuration¶

Restrict to Local network¶

If you are planning to use ejabberd API for admin purpose, it is often enough to configure it to be available local commands. Access is thus generally limited by IP addresses, either restricted to localhost only, or restricted to one of your platform back-end.

Make sure an ejabberd_http listener is using mod_http_api on a given root URL and on a desired port:
```
listen:
  -
    port: 5281
    module: ejabberd_http
    ip: 127.0.0.1
    request_handlers:
      /api: mod_http_api
```
The ip option ensures it listens only on the local interface (127.0.0.1) instead of listening on all interface (0.0.0.0).
By defining api_permissions, you can then allow HTTP request from a specific IP to trigger API commands execution without user credentials:
```
api_permissions:
  "API used from localhost allows all calls":
    who:
      ip: 127.0.0.1/8
    what:
      - "*"
      - "!stop"
      - "!start"
```
Note: stop and start commands are disabled in that example as they are usually restricted to ejabberdctl command-line tool. They are consider too sensitive to be exposed through API.

Now you can query the API, for example:

curl '127.0.0.1:5281/api/registered_users?host=localhost'

["user2","user8"]

Encryption¶

If you already defined certificates and your connection is not on a local network, you may want to use encryption.

Setup encryption like this:

listen:
  -
    port: 5281
    module: ejabberd_http
    tls: true
    request_handlers:
      /api: mod_http_api

Now you can query using HTTPS:

curl 'https://127.0.0.1:5281/api/registered_users?host=localhost'

["user2","user8"]

If you are using a self-signed certificate, you can bypass the corresponding error message:

curl --insecure 'https://127.0.0.1:5281/api/registered_users?host=localhost'

["user2","user8"]

Basic Authentication¶

Quite probably you will want to require authentication to execute API queries, either using basic auth or OAuth.

Assuming you have the simple listener:

listen:
  -
    port: 5281
    module: ejabberd_http
    ip: 127.0.0.1
    request_handlers:
      /api: mod_http_api

Define an ACL with the account that you will use to authenticate:
```
acl:
  apicommands:
    user: john@localhost
```

Allow only that ACL to use the API:

api_permissions:
  "some playing":
    from:
      - ejabberd_ctl
      - mod_http_api
    who:
      acl: apicommands
    what: "*"

If that account does not yet exist, register it:

ejabberdctl register john localhost somePass

Now, when sending an API query, provide the authentication for that account:

curl --basic --user john@localhost:somePass \
     '127.0.0.1:5281/api/registered_users?host=localhost'

["user2","user8","john"]

Example Python code:

import requests

url = "http://localhost:5281/api/registered_users"
data = {
    "host": "localhost"
}

res = requests.post(url, json=data, auth=("john@localhost", "somePass"))

print(res.text)

OAuth Authentication¶

Before using OAuth to interact with ejabberd API, you need to configure OAuth support in ejabberd.

Here are example entries to check / change in your ejabberd configuration file:

Add a request handler for OAuth:

listen:
  -
    # Using a separate port for oauth and API to make it easy to protect it
    # differently than BOSH and WebSocket HTTP interface.
    port: 5281
    # oauth and API only listen on localhost interface for security reason
    # You can set ip to 0.0.0.0 to open it widely, but be careful!
    ip: 127.0.0.1
    module: ejabberd_http
    request_handlers:
      /api: mod_http_api
      /oauth: ejabberd_oauth

Set the oauth_access top-level option to allow token creation:
```
oauth_access: all
```
Define an ACL with the account that you will use to authenticate:
```
acl:
  apicommands:
    user: john@localhost
```

You can then configure the OAuth commands you want to expose and who can use them:

api_permissions:
  "admin access":
    who:
      oauth:
        scope: "ejabberd:admin"
        scope: "registered_users"
        access:
          allow:
            acl: apicommands
    what: "*"

If that account does not yet exist, register it:

ejabberdctl register john localhost somePass

Request an authorization token. A quick way is using ejabberdctl:

ejabberdctl oauth_issue_token user123@localhost 3600 ejabberd:admin
erHymcBiT2r0QsuOpDjIrsEvnOS4grkj   [<<"ejabberd:admin">>]   3600 seconds

Now, when sending an API query, provide the authentication for that account:

curl -H "Authorization: Bearer erHymcBiT2r0QsuOpDjIrsEvnOS4grkj" \
     '127.0.0.1:5281/api/registered_users?host=localhost'

["user2","user8","john"]

Or quite simply:

curl --oauth2-bearer erHymcBiT2r0QsuOpDjIrsEvnOS4grkj \
     '127.0.0.1:5281/api/registered_users?host=localhost'

["user2","user8","john"]