{"id":28724147,"url":"https://github.com/processone/ejabberd-api","last_synced_at":"2025-06-15T10:09:21.119Z","repository":{"id":48873449,"uuid":"62224349","full_name":"processone/ejabberd-api","owner":"processone","description":"ejabberd API library in Go and multi-platform command-line tool","archived":false,"fork":false,"pushed_at":"2024-07-17T16:00:16.000Z","size":90,"stargazers_count":24,"open_issues_count":3,"forks_count":11,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-11-13T13:17:10.635Z","etag":null,"topics":["ejabberd","ejabberd-api","xmpp"],"latest_commit_sha":null,"homepage":"http://www.process-one.net/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/processone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-29T12:31:42.000Z","updated_at":"2024-09-04T22:55:23.000Z","dependencies_parsed_at":"2024-06-19T00:20:24.273Z","dependency_job_id":"7fb79c27-a0fb-4a85-b554-4b96f938b7b8","html_url":"https://github.com/processone/ejabberd-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/processone/ejabberd-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processone%2Fejabberd-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processone%2Fejabberd-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processone%2Fejabberd-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processone%2Fejabberd-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/processone","download_url":"https://codeload.github.com/processone/ejabberd-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processone%2Fejabberd-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259957280,"owners_count":22937549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ejabberd","ejabberd-api","xmpp"],"created_at":"2025-06-15T10:09:19.867Z","updated_at":"2025-06-15T10:09:21.097Z","avatar_url":"https://github.com/processone.png","language":"Go","readme":"# ejabberd API library and command-line tool\n\n[![Build Status](https://semaphoreci.com/api/v1/processone/ejabberd-api/branches/master/shields_badge.svg)](https://semaphoreci.com/processone/ejabberd-api)\n[![Coverage Status](https://coveralls.io/repos/github/processone/ejabberd-api/badge.svg?branch=master)](https://coveralls.io/github/processone/ejabberd-api?branch=master)\n\nThis tool is composed of two components:\n\n- A command-line tool to interact with ejabberd through ReST API calls\n  from the command-line, from any server type or desktop (Linux, OSX,\n  Windows).\n- An implementation of ejabberd API client library in Go. It can be\n  used to interact with ejabberd from backend applications developed\n  in Go programming language.\n\n## Installation\n\nBoth the library and the command-line tool can be installed from\nsource with `go get` tool.\n\nIf you have go installed in your environment you can install\n`ejabberd` command-line tool with:\n\n```bash\ngo install -v github.com/processone/ejabberd-api/cmd/ejabberd@master\n```\nOnce the get completes, you should find your new `ejabberd` (or `ejabberd.exe`) executable sitting inside `$GOPATH/bin/`.\n\n## Configuring ejabberd OAuth API\n\nBefore being able to interact with ejabberd API, you need to configure\nejabberd with OAuth support enabled. This is is documented in\n[ejabberd OAuth support](https://docs.ejabberd.im/developer/ejabberd-api/oauth/).\n\nHere are example entries to check / change in your ejabberd\nconfiguration file:\n\n1. Add a [listener](https://docs.ejabberd.im/admin/configuration/listen/) for OAuth and ReST API:\n\n   ```yaml\n   listen:\n     -\n       # Using a separate port for oauth and API to make it easy to protect it\n       # differently than BOSH and Websocket HTTP interface.\n       port: 5281\n       # oauth and API only listen on localhost interface for security reason\n       # You can set ip to 0.0.0.0 to open it widely, but be careful!\n       ip: 127.0.0.1\n       module: ejabberd_http\n       request_handlers:\n         /oauth: ejabberd_oauth\n         /api: mod_http_api\n   ```\n\n2. You can then configure the OAuth commands you want to expose. Check\n   [`api_permissions`](https://docs.ejabberd.im/developer/ejabberd-api/permissions/)\n   to make sure ACL for passing commands as admins are set properly:\n\n   ```yaml\n   api_permissions:\n     \"admin access\":\n       who:\n         oauth:\n           scope: \"ejabberd:admin\"\n           access:\n             allow:\n               user: admin@localhost\n       what:\n         - \"register\"\n         - \"change_password\"\n   \n   # Tokens are valid for a year as default:\n   oauth_expire: 31536000\n   oauth_access: all\n   ```\n\n3. Finally, make sure to enable the modules that provide the commands you\n   want to use, for example:\n\n   ```yaml\n   modules:\n     mod_admin_extra: {}\n   ```\n\n## ejabberd command-line tool\n\nThe `ejabberd` command-line tool allows you to interact with your ejabberd server\nby using ejabberd's ReST API. It relies on OAuth tokens and scope to define the command\nthe user will be allowed to call.\n\n### Usage\n\n1. Generating an OAuth token:\n\n   To use the `ejabberd` command-line tool, you first need to generate an OAuth\n   token.\n\n   It can be done, for example, with the following command:\n\n   ```bash\n   ejabberd token -j admin@localhost -p mypassword -s ejabberd:admin\n   ```\n\n   This will generate a `.ejabberd-oauth.json` file containing your\n   credentials. Keep the file secret, as it will grant access to command\n   available in the requested scope on your behalf.\n\n2. Calling ejabberd API from the command-line, using your token file. For example:\n\n   ```bash\n   ejabberd stats registeredusers\n   ```\n\n3. You can also try to call any available command thanks to the generic `call` command. Do not forget `-a` parameter for commands that requires admin rights. For example:\n\n   ```bash\n   cat register.json\n   {\"user\":\"test1\", \"host\":\"localhost\", \"password\":\"somePassW0rd\"}\n   \n   ejabberd call --name register -a --data-file=register.json\n   ```\n\n### Generating Bash/ZSH completion\n\nYou can generate Bash completion with following command:\n\n```bash\n./ejabberd --completion-script-bash\n```\n\nYou can generate ZSH completion with following command:\n\n```bash\n./ejabberd --completion-script-zsh\n```\n\nTo be able to use completion for Bash, you can type or add in your\n`bash_profile` (or equivalent):\n\n```bash\neval \"$(ejabberd --completion-script-bash)\"\n```\n\nFor ZSH, you can use:\n\n```bash\neval \"$(ejabberd --completion-script-zsh)\"\n```\n\n### Available commands\n\n* **token**: Get OAuth token. This is needed before calling others commands.\n* **stats**: Retrieve some stats from ejabberd.\n\nTo get a full list of commands and their options:\n\n```bash\nejabberd --help-long\n```\n\n### OAuth Token file format\n\nAs a default, the token is stored in a file called\n`./.ejabberd-oauth.json` when using the command `token` and read from\nthe same file when you use any other commands.\n\nOption `-f file` will let you point to another file.\n\nThe file contains a JSON structure with the following fields:\n\n* **access_token**: Actual token value.\n* **endpoint**: Base URL.\n* **jid**: JID for which user the token was generated.\n* **scope**: OAuth scope for which the token was generated.\n* **expiration**: Expiration date for the token.\n\nFor example:\n\n```json\n{\"access_token\":\"AaQTb0PUZqeZhFKYoaTQBb4KKkCTAolE\",\n \"endpoint\":\"http://localhost:5281/\",\n \"jid\":\"admin@localhost\",\n \"scope\":\"ejabberd:admin\",\n \"expiration\":\"2017-07-23T13:53:08.326421575+02:00\"}\n```\n\n## Development\n\n### Local build\n\n```bash\ngo build -o ejabberd cmd/ejabberd/main.go\n```\n\n### Running tests\n\nYou can run tests from repository clone with command:\n\n```bash\ngo test -race -v ./.\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprocessone%2Fejabberd-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprocessone%2Fejabberd-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprocessone%2Fejabberd-api/lists"}