{"id":21175537,"url":"https://github.com/android-sms-gateway/server","last_synced_at":"2026-06-15T03:04:32.601Z","repository":{"id":228703438,"uuid":"711403132","full_name":"android-sms-gateway/server","owner":"android-sms-gateway","description":"The SMS Gateway for Android™ Server enables the dispatch of SMS messages through Android devices without requiring direct Internet access to them.","archived":false,"fork":false,"pushed_at":"2026-06-01T02:26:09.000Z","size":3827,"stargazers_count":124,"open_issues_count":2,"forks_count":45,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-06-01T04:17:23.329Z","etag":null,"topics":["android","api","backend","mobile-messaging","remote-sms","rest-api","server","sms-gateway"],"latest_commit_sha":null,"homepage":"https://docs.sms-gate.app","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/android-sms-gateway.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-10-29T06:37:33.000Z","updated_at":"2026-05-31T21:41:30.000Z","dependencies_parsed_at":"2024-05-22T02:46:13.979Z","dependency_job_id":"608414cc-b1ac-4556-b7d0-042c724b5179","html_url":"https://github.com/android-sms-gateway/server","commit_stats":null,"previous_names":["capcom6/sms-gateway","android-sms-gateway/server"],"tags_count":128,"template":false,"template_full_name":null,"purl":"pkg:github/android-sms-gateway/server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/android-sms-gateway%2Fserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/android-sms-gateway%2Fserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/android-sms-gateway%2Fserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/android-sms-gateway%2Fserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/android-sms-gateway","download_url":"https://codeload.github.com/android-sms-gateway/server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/android-sms-gateway%2Fserver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34345580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["android","api","backend","mobile-messaging","remote-sms","rest-api","server","sms-gateway"],"created_at":"2024-11-20T16:59:49.649Z","updated_at":"2026-06-15T03:04:32.559Z","avatar_url":"https://github.com/android-sms-gateway.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![Apache 2.0 License][license-shield]][license-url]\n\n# SMSGate Server\n\nThis server acts as the backend component of the [SMSGate](https://github.com/capcom6/android-sms-gateway), facilitating the sending of SMS messages through connected Android devices. It includes a RESTful API for message management, integration with Firebase Cloud Messaging (FCM), and a database for persistent storage.\n\n## Table of Contents\n\n- [SMSGate Server](#smsgate-server)\n  - [Table of Contents](#table-of-contents)\n  - [Features](#features)\n  - [Prerequisites](#prerequisites)\n  - [Quickstart](#quickstart)\n  - [Work modes](#work-modes)\n  - [JWT Authentication](#jwt-authentication)\n    - [Configuration](#configuration)\n    - [Token Management](#token-management)\n      - [Generate Token Pair](#generate-token-pair)\n      - [Refresh Access Token](#refresh-access-token)\n      - [Revoke Token](#revoke-token)\n    - [Using JWT Tokens](#using-jwt-tokens)\n    - [Available Scopes](#available-scopes)\n  - [Contributing](#contributing)\n  - [License](#license)\n  - [Legal Notice](#legal-notice)\n\n## Features\n\n- **SMS Messaging**: Dispatch SMS and data messages through a RESTful API.\n- **Message Status**: Retrieve status for sent messages.\n- **Device Management**: View information about connected Android devices.\n- **Webhooks**: Configure webhooks for event-driven notifications.\n- **Health Monitoring**: Access health check endpoints to ensure system integrity.\n- **Access Control**: Operate in either public mode for open access or private mode for restricted access.\n- **Data SMS Support**: Send/receive binary payloads via SMS with Base64 encoding and port-based routing.\n- **JWT Authentication**: Secure API access with JSON Web Tokens, including access and refresh token support for enhanced security.\n\n## Prerequisites\n\n- Go (for development and testing purposes)\n- Docker and Docker Compose (for Docker-based setup)\n- A configured MySQL/MariaDB database\n\n## Quickstart\n\nThe easiest way to get started with the server is to use the Docker-based setup in Private Mode. In this mode device registration endpoint is protected, so no one can register a new device without knowing the token.\n\n1. Set up MySQL or MariaDB database.\n2. Create config.yml, based on [config.example.yml](configs/config.example.yml). The most important sections are `database`, `http` and `gateway`. Environment variables can be used to override values in the config file.\n    1. In `gateway.mode` section set `private`.\n    2. In `gateway.private_token` section set the access token for device registration in private mode. This token must be set on devices with private mode active.\n    3. In `gateway.upstream_url` section set the upstream server base URL used for private-mode push notifications. (default: `https://api.sms-gate.app/upstream/v1`).\n    4. (Optional) In `jwt` section configure JWT authentication:\n       - Set `secret` to a secure random string (minimum 32 characters)\n       - Configure `access_ttl` (default: 15m) and `refresh_ttl` (default: 720h)\n       - Set `issuer` to identify your server\n3. Start the server in Docker: `docker run -p 3000:3000 -v ./config.yml:/app/config.yml capcom6/sms-gateway:latest`.\n4. Set up private mode on devices.\n5. Use started private server with the same API as the public server at [api.sms-gate.app](https://api.sms-gate.app).\n\nSee also [docker-compose.yml](deployments/docker-compose/docker-compose.yml) for Docker-based setup.\n\n## Work modes\n\nThe server has two work modes: public and private. The public mode allows anonymous device registration and used at [api.sms-gate.app](https://api.sms-gate.app). Private mode can be used to send sensitive messages and running server in local infrastructure.\n\nIn most operations public and private modes are the same. But there are some differences:\n\n- `POST /api/mobile/v1/device` endpoint is protected by API key in private mode. So it is not possible to register a new device on private server without knowing the token.\n- FCM notifications from private server are sent through `api.sms-gate.app`. Notifications don't contain any sensitive data like phone numbers or message text.\n\nSee also [private mode discussion](https://github.com/capcom6/android-sms-gateway/issues/20).\n\n## JWT Authentication\n\nThe server supports JWT (JSON Web Token) authentication for secure API access. When enabled, you can generate access tokens with specific scopes and refresh them without re-authenticating.\n\n### Configuration\n\nTo enable JWT authentication, configure the `jwt` section in your [`config.yml`](configs/config.example.yml):\n\n```yaml\njwt:\n  secret: your-secure-secret-key-minimum-32-characters  # Required, minimum 32 characters\n  access_ttl: 15m                                       # Access token time-to-live (default: 15m)\n  refresh_ttl: 720h                                     # Refresh token time-to-live (default: 720h)\n  issuer: your-server-name                              # Optional issuer identifier\n```\n\n**Important**: The `secret` must be at least 32 characters long. The `refresh_ttl` must be greater than `access_ttl`.\n\n### Token Management\n\n#### Generate Token Pair\n\nGenerate an access token and refresh token using Basic authentication:\n\n```http\nPOST /api/3rdparty/v1/auth/token HTTP/1.1\nAuthorization: Basic \u003cbase64-encoded-credentials\u003e\nContent-Type: application/json\n\n{\n    \"ttl\": 3600,\n    \"scopes\": [\n        \"messages:send\",\n        \"messages:read\",\n        \"devices:list\",\n        \"devices:delete\",\n        \"webhooks:list\",\n        \"webhooks:write\",\n        \"settings:read\",\n        \"settings:write\",\n        \"logs:read\"\n    ]\n}\n```\n\nResponse:\n```json\n{\n    \"id\": \"token-jti\",\n    \"token_type\": \"Bearer\",\n    \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n    \"refresh_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n    \"expires_at\": \"2026-03-12T02:00:00Z\"\n}\n```\n\n#### Refresh Access Token\n\nUse the refresh token to obtain a new access token:\n\n```http\nPOST /api/3rdparty/v1/auth/token/refresh HTTP/1.1\nAuthorization: Bearer \u003crefresh_token\u003e\n```\n\n#### Revoke Token\n\nRevoke a specific token by its JTI (JWT ID):\n\n```http\nDELETE /api/3rdparty/v1/auth/token/\u003cjti\u003e HTTP/1.1\nAuthorization: Basic \u003cbase64-encoded-credentials\u003e\n```\n\n### Using JWT Tokens\n\nOnce you have an access token, use it in the `Authorization` header:\n\n```http\nGET /api/3rdparty/v1/messages HTTP/1.1\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n### Available Scopes\n\nThe following scopes are available for token generation:\n\n- `devices:delete` - Delete devices\n- `devices:list` - List connected devices\n- `inbox:list` - List incoming messages with filters\n- `inbox:read` - Read incoming messages\n- `logs:read` - Read server logs\n- `messages:export` - Export messages\n- `messages:list` - List messages\n- `messages:read` - Read individual messages\n- `messages:send` - Send SMS messages\n- `settings:read` - Read server settings\n- `settings:write` - Modify server settings\n- `tokens:manage` - Generate and revoke tokens\n- `webhooks:delete` - Delete webhooks\n- `webhooks:list` - List webhooks\n- `webhooks:write` - Create and update webhooks\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nDistributed under the Apache-2.0 license. See [LICENSE](LICENSE) for more information.\n\n## Legal Notice\n\nAndroid is a trademark of Google LLC.\n\n[contributors-shield]: https://img.shields.io/github/contributors/android-sms-gateway/server.svg?style=for-the-badge\n[contributors-url]: https://github.com/android-sms-gateway/server/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/android-sms-gateway/server.svg?style=for-the-badge\n[forks-url]: https://github.com/android-sms-gateway/server/network/members\n[stars-shield]: https://img.shields.io/github/stars/android-sms-gateway/server.svg?style=for-the-badge\n[stars-url]: https://github.com/android-sms-gateway/server/stargazers\n[issues-shield]: https://img.shields.io/github/issues/android-sms-gateway/server.svg?style=for-the-badge\n[issues-url]: https://github.com/android-sms-gateway/server/issues\n[license-shield]: https://img.shields.io/github/license/android-sms-gateway/server.svg?style=for-the-badge\n[license-url]: https://github.com/android-sms-gateway/server/blob/master/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandroid-sms-gateway%2Fserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandroid-sms-gateway%2Fserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandroid-sms-gateway%2Fserver/lists"}