{"id":29178228,"url":"https://github.com/codeshelldev/secured-signal-api","last_synced_at":"2026-04-07T15:01:26.629Z","repository":{"id":301765559,"uuid":"993258010","full_name":"CodeShellDev/secured-signal-api","owner":"CodeShellDev","description":"Secure API Gateway Proxy for Signal CLI REST API adding many QoL and Security Features","archived":false,"fork":false,"pushed_at":"2026-04-07T13:19:46.000Z","size":2606,"stargazers_count":29,"open_issues_count":6,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-07T13:20:20.417Z","etag":null,"topics":["api-gateway","codeshelldev","docker-container","quality-of-life","secure-proxy","signal-cli-rest-api","signal-messenger"],"latest_commit_sha":null,"homepage":"https://codeshelldev.github.io/secured-signal-api","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CodeShellDev.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":"2025-05-30T13:35:20.000Z","updated_at":"2026-04-07T12:43:32.000Z","dependencies_parsed_at":"2025-12-18T01:10:42.150Z","dependency_job_id":null,"html_url":"https://github.com/CodeShellDev/secured-signal-api","commit_stats":null,"previous_names":["codeshelldev/secured-signal-api"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/CodeShellDev/secured-signal-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShellDev%2Fsecured-signal-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShellDev%2Fsecured-signal-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShellDev%2Fsecured-signal-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShellDev%2Fsecured-signal-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodeShellDev","download_url":"https://codeload.github.com/CodeShellDev/secured-signal-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShellDev%2Fsecured-signal-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31516839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["api-gateway","codeshelldev","docker-container","quality-of-life","secure-proxy","signal-cli-rest-api","signal-messenger"],"created_at":"2025-07-01T18:21:36.487Z","updated_at":"2026-04-07T15:01:26.538Z","avatar_url":"https://github.com/CodeShellDev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cimg align=\"center\" width=\"1048\" height=\"512\" alt=\"Secure API Gateway Proxy for Signal CLI REST API\" src=\"https://github.com/codeshelldev/secured-signal-api/raw/refs/heads/docs/static/img/brand/banner.png\" /\u003e\n\n\u003ch3 align=\"center\"\u003eSecure API Gateway Proxy for \u003ca href=\"https://github.com/bbernhard/signal-cli-rest-api\"\u003eSignal CLI REST API\u003c/a\u003e\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\ntoken-based authentication,\nendpoint restrictions, placeholders, flexible configuration\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n🔒 Secure · ⭐️ Configurable · 🚀 Easy to Deploy with Docker\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/codeshelldev/secured-signal-api/releases\"\u003e\n    \u003cimg \n\t\tsrc=\"https://img.shields.io/github/v/release/codeshelldev/secured-signal-api?sort=semver\u0026logo=github\u0026label=Release\" \n\t\talt=\"GitHub release\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/codeshelldev/secured-signal-api/stargazers\"\u003e\n    \u003cimg \n\t\tsrc=\"https://img.shields.io/github/stars/codeshelldev/secured-signal-api?style=flat\u0026logo=github\u0026label=Stars\" \n\t\talt=\"GitHub stars\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://matrix.to/#/#secured-signal-api:matrix.org\"\u003e\n\t  \u003cimg \n\t\t  alt=\"Matrix\" \n\t\t  src=\"https://img.shields.io/matrix/secured-signal-api%3Amatrix.org?style=flat\u0026color=blue\u0026logo=matrix\u0026label=Chat\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/codeshelldev/secured-signal-api/pkgs/container/secured-signal-api\"\u003e\n    \u003cimg\n    src='https://img.shields.io/badge/Image%20Size-9.81%20MiB-_?color=2344cc11'\n    alt=\"Docker image Pulls\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/codeshelldev/secured-signal-api/pkgs/container/secured-signal-api\"\u003e\n    \u003cimg \n\t\tsrc=\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fghcr-badge.elias.eu.org%2Fapi%2Fcodeshelldev%2Fsecured-signal-api%2Fsecured-signal-api\u0026query=downloadCount\u0026label=Pulls\u0026color=2344cc11\u0026logo=docker\"\n\t\talt=\"Docker image Pulls\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\n    \u003cimg \n\t\tsrc=\"https://img.shields.io/badge/License-MIT-green.svg\"\n\t\talt=\"License: MIT\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n## Contents\n\n\u003e [!IMPORTANT]\n\u003e Check out the [**Official Documentation**](https://codeshelldev.github.io/secured-signal-api) for up-to-date instructions and additional content!\n\n- [Getting Started](#getting-started)\n- [Usage](#usage)\n- [Features](#features)\n- [Configuration](#configuration)\n  - [Endpoints Restrictions](https://codeshelldev.github.io/secured-signal-api/docs/configuration/endpoints)\n  - [Placeholder Variables](https://codeshelldev.github.io/secured-signal-api/docs/configuration/variables)\n  - [Field Policies](https://codeshelldev.github.io/secured-signal-api/docs/configuration/field-policies)\n  - [Field Mappings](https://codeshelldev.github.io/secured-signal-api/docs/configuration/field-mappings)\n  - [Message Template](https://codeshelldev.github.io/secured-signal-api/docs/configuration/message-template)\n  - [Port Restrictions](https://codeshelldev.github.io/secured-signal-api/docs/configuration/port)\n  - [Hostname Restrictions](https://codeshelldev.github.io/secured-signal-api/docs/configuration/hostnames)\n  - [IP Filter](https://codeshelldev.github.io/secured-signal-api/docs/configuration/ip-filter)\n  - [Rate Limiting](https://codeshelldev.github.io/secured-signal-api/docs/configuration/rate-limiting)\n  - [Trusted Proxies](https://codeshelldev.github.io/secured-signal-api/docs/configuration/trusted-proxies)\n  - [Trusted IPs](https://codeshelldev.github.io/secured-signal-api/docs/configuration/trusted-ips)\n  - [Log Level](https://codeshelldev.github.io/secured-signal-api/docs/configuration/log-level)\n  - [Port](https://codeshelldev.github.io/secured-signal-api/docs/configuration/port)\n  - [Hostnames](https://codeshelldev.github.io/secured-signal-api/docs/configuration/hostnames)\n  - [Auth Methods](https://codeshelldev.github.io/secured-signal-api/docs/configuration/auth)\n  - [CORS](https://codeshelldev.github.io/secured-signal-api/docs/configuration/cors)\n- [Reverse Proxy](https://codeshelldev.github.io/secured-signal-api/docs/reverse-proxy)\n- [Integrations](https://codeshelldev.github.io/secured-signal-api/docs/integrations)\n- [Contributing](#contributing)\n- [Support](#support)\n- [Help](#help)\n- [License](#license)\n- [Legal](#legal)\n\n## Getting Started\n\n### Installation\n\nGet the latest version of the `docker-compose.yaml` file:\n\n```yaml\nservices:\n  signal-api:\n    image: bbernhard/signal-cli-rest-api:latest\n    container_name: signal-api\n    environment:\n      - MODE=normal\n    volumes:\n      - ./data:/home/.local/share/signal-cli\n    restart: unless-stopped\n    networks:\n      backend:\n        aliases:\n          - signal-api\n\n  secured-signal:\n    image: ghcr.io/codeshelldev/secured-signal-api:latest\n    container_name: secured-signal\n    environment:\n      API__URL: http://signal-api:8080\n      SETTINGS__MESSAGE__VARIABLES__RECIPIENTS: \"[+123400002, +123400003, +123400004]\"\n      SETTINGS__MESSAGE__VARIABLES__NUMBER: \"+123400001\"\n      API__TOKENS: \"[LOOOOOONG_STRING]\"\n    ports:\n      - \"8880:8880\"\n    volumes:\n      - ./db:/db\n    restart: unless-stopped\n    networks:\n      backend:\n        aliases:\n          - secured-signal-api\n\n\nnetworks:\n  backend:\n```\n\n\u003e [!IMPORTANT]\n\u003e In this documentation, we'll be using `sec-signal-api:8880` as the host for simplicity,\n\u003e please replace it with your actual container/host IP, port, or hostname\n\n#### API Tokens\n\nNow head to [configuration](https://codeshelldev.github.io/secured-signal-api/docs/configuration/api-tokens) and define some **API tokens**.\n\n\u003e [!TIP]\n\u003e This recommendation is part of the [**best practices**](https://codeshelldev.github.io/secured-signal-api/docs/best-practices)\n\n### Setup\n\nOnce you have installed **Secured Signal API** you can [register or link a signal account](https://codeshelldev.github.io/secured-signal-api/docs/getting-started/setup).\n\n## Usage\n\n### Basic\n\nHere is a quick command to see if you've correctly followed the [setup instructions](https://codeshelldev.github.io/secured-signal-api/docs/getting-started/setup):\n\n```bash\ncurl -X POST \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"message\":\"Hello, World!\", \"number\":\"\u003cfrom\u003e\", \"recipients\":[\"\u003cto\u003e\"]}' \\\n    'http://sec-signal-api:8880/v2/send'\n```\n\nThis will send `Hello, World!` to `\u003cto\u003e` from `\u003cfrom\u003e`.\n\n### Auth\n\n**Secured Signal API** implements 5 auth methods:\n\n| Method      | Example                                                                                                      |\n| :---------- | :----------------------------------------------------------------------------------------------------------- |\n| Bearer Auth | `Authorization: Bearer API_TOKEN` (header)                                                                   |\n| Basic Auth  | `Authorization: Basic base64(api:API_TOKEN)` (header)\u003cbr/\u003e`http://api:API_TOKEN@host:port` (client specific) |\n| Query Auth  | `http://host:port/abc?@auth=API_TOKEN` (query parameter)                                                     |\n| Path Auth   | `http://host:port/@auth=API_TOKEN/abc` (path parameter)                                                      |\n| Body Auth   | `{ \"auth\": \"API_TOKEN\" }` (request body field)                                                               |\n\n\u003e [!WARNING]\n\u003e **Query** and **Path** auth are disabled by default and [must be enabled in the config](https://codeshelldev.github.io/secured-signal-api/docs/configuration/auth)\n\n**Example:**\n\n```bash\ncurl -X POST \\\n    -H \"Content-Type: application/json\" \\\n    -H \"Authorization: Bearer API_TOKEN\" \\\n    -d '{\"message\":\"Hello, World!\", \"number\":\"\u003cfrom\u003e\", \"recipients\":[\"\u003cto\u003e\"]}' \\\n    'http://sec-signal-api:8880/v2/send'\n```\n\n## Features\n\n### Message Template\n\n\u003e _Structure your messages_\n\n**Message Templates** can be used to customize your final message after preprocessing.\nLook at this complex template for example:\n\n```yaml\nsettings:\n  message:\n    messageTemplate: |\n      {{- $greeting := \"Hello\" -}}\n      {{ $greeting }}, {{ @name }}!\n      {{ if @age -}}\n      You are {{ @age }} years old.\n      {{- else -}}\n      Age unknown.\n      {{- end }}\n      Your friends:\n      {{- range @friends }}\n      - {{ . }}\n      {{- else }}\n      You have no friends.\n      {{- end }}\n      Profile details:\n      {{- range $key, $value := @profile }}\n      - {{ $key }}: {{ $value }}\n      {{- end }}\n      {{ define \"footer\" -}}\n      This is the footer for {{ @name }}.\n      {{- end }}\n      {{ template \"footer\" . -}}\n\n```\n\nIt can extract needed data from the body and headers to then process them using Go's templating library\nand finally output a message packed with so much information.\n\nHead to [Configuration](https://codeshelldev.github.io/secured-signal-api/docs/configuration/message-template) to see how-to use.\n\n### Placeholders\n\n\u003e _Time saving and flexible_\n\n**Placeholders** are one of the highlights of Secured Signal API,\nthese have saved me, and will save many others, much time by, for example, not having to change your phone number in every service separately.\n\nTake a look at the [usage](https://codeshelldev.github.io/secured-signal-api/docs/usage/advanced).\n\n### Field Mappings\n\n\u003e _Standardize output_\n\n**Field Mappings** are very useful for when your favorite service does not officially support **Secured Signal API** (or Signal CLI REST API).\nWith this feature you have the power to do it yourself, just extract what's needed and then integrate with any of the other features.\n\nInterested? [Take a look](https://codeshelldev.github.io/secured-signal-api/docs/configuration/field-mappings).\n\n### Field Policies\n\n**Field Policies** are a great way to disallow specific fields or even disallowing fields with unwanted values.\nThis is really helpful when trying to block certain numbers from using certain tokens, and therefor mitigating risks of unwanted use of a token.\n\nFind more about this feature [here](https://codeshelldev.github.io/secured-signal-api/docs/configuration/field-policies).\n\n### Rate Limiting\n\n**Rate Limiting** is used for limiting requests and to stop server overload, because of DDoS attacks, malconfigured clients, or malicious actors.  \nIt ensures fair usage per token by controlling how many requests can be processed within a defined period.\n\nLimit those rates [here](https://codeshelldev.github.io/secured-signal-api/docs/configuration/rate-limiting).\n\n### Endpoints\n\n\u003e _Block unwanted access_\n\n**Endpoints** are used for restricting unauthorized access and for ensuring least privilege.\n\n[Let's start blocking then!](https://codeshelldev.github.io/secured-signal-api/docs/configuration/endpoints)\n\n### IP Filters\n\n**IP Filters** are used for restricting access to **Secured Signal API** by blocking or specifically allowing IPs and CIDR ranges.\n\nConfigure your _mini firewall_ [here](https://codeshelldev.github.io/secured-signal-api/docs/configuration/ip-filter).\n\n### CORS\n\n\u003e _Enable secure browser access_\n\n**CORS** support allows web applications running in a browser to access the API directly from a different origin.\n\nLearn more about browser integration [here](https://codeshelldev.github.io/secured-signal-api/docs/configuration/cors).\n\n## Configuration\n\n### Environment Variables\n\nWhilst being a bit **restrictive** environment variables are a great way to configure Secured Signal API.\n\nSuppose you want to set a new [placeholder](https://codeshelldev.github.io/secured-signal-api/docs/usage/advanced#placeholders) `NUMBER` in your environment…\n\n```yaml\nenvironment:\n  SETTINGS__MESSAGE__VARIABLES__NUMBER: \"+123400001\"\n```\n\nThis would internally be converted into `settings.message.variables.number` matching the config formatting.\n\n\u003e [!IMPORTANT]\n\u003e Single underscores `_` are removed during conversion, whereas double underscores `__` convert the variable into a nested object (with `__` replaced by `.`)\n\n### Config Files\n\n```md\nconfig.yml\ntokens\n├── notify.yml\n└── totp.yml\n```\n\nConfig files are the **recommended** way to configure and use **Secured Signal API**,\nthey are **flexible**, **extensible** and really **easy to use**.\n\n\u003e [!TIP]\n\u003e Configs also support placeholders, for example:\n\u003e `${{ .env.NUMBER }}` or `${{ .vars.RECIPIENTS }}`\n\u003e\n\u003e - Use `.vars` for placeholders from [variables](https://codeshelldev.github.io/secured-signal-api/docs/variables)\n\u003e - and `.env` for environment variables\n\n\u003e [!NOTE]\n\u003e To change the internal config file location set `CONFIG_PATH` in your **environment** to an absolute path (default: `/config/config.yml`)\n\nThis example config shows all the individual settings that can be applied:\n\n```yaml\n## Example Config (all configurations shown)\nservice:\n  logLevel: info\n  port: 8880\n  hostnames:\n    - mydomain.com\n\napi:\n  url: http://signal-api:8080\n  tokens: [token1, token2]\n  auth:\n    methods: [bearer, basic, body]\n    tokens:\n      - set: [pathToken1, pathToken2]\n        methods: [path]\n      - set: [queryAndBodyToken]\n        methods: [body, query]\n\nsettings:\n  http:\n    responseHeaders:\n      X-Custom: \"xyz\"\n\n  message:\n    messageTemplate: |\n      You've got a Notification:\n      {{ @message }} \n      At {{ @data.timestamp }} on {{ @data.date }}.\n      Send using {{ .NUMBER }}.\n\n    templating:\n      body: true\n      query: true\n      path: true\n\n    scheduling:\n      enabled: true\n      maxHorizon: 10d\n\n    injecting:\n      urlToBody:\n        query: true\n        path: true\n\n    variables:\n      number: \"+123400001\"\n      recipients: [\"+123400002\", \"group.id\", \"user.id\"]\n      text_mode: \"${{ .env.TEXT_MODE }}\"\n\n    fieldMappings:\n      \"@message\":\n        - field: \"msg\"\n          score: 100\n\n  access:\n    trustedIPs:\n      - 192.168.1.10\n\n    trustedProxies:\n      - 172.20.0.100\n\n    ipFilter:\n      allowed:\n        - 192.168.1.10\n        - 192.168.2.0/24\n      blocked:\n        - 192.168.2.44\n\n    endpoints:\n      allowed:\n        - pattern: /v2/send\n        - pattern: /v1/receive/${{ .vars.NUMBER }}\n      blocked:\n        - pattern: /v1/about\n        - pattern: /v1/receive/[^0]+\n          matchType: regex\n\n    rateLimiting:\n      limit: 100\n      period: 1h\n\n    fieldPolicies:\n      \"@number\":\n        - value: \"+123400003\"\n          action: block\n        - value: \"+12340000[4-9]\"\n          matchType: regex\n          action: block\n\n    cors:\n      methods: [GET, POST]\n      headers: [\"Content-Type\", \"Accept-Language\"]\n      origins:\n        - url: \"https://domain.com\"\n          methods: [GET]\n          headers: [\"Content-Type\"]\n\n```\n\n#### Token Configs\n\n```\ntokens\n├── notify.yml\n└── totp.yml\n```\n\n\u003e But wait! There is more… 😁\n\nToken configs can be used to create **per-token** defined **overrides** and settings.\n\n\u003e [!NOTE]\n\u003e Create them under `TOKENS_PATH` (default: `config/tokens/`)\n\nHere is an example:\n\n```yaml\n## Example Token Config (overwrites)\nservice:\n  logLevel: info\n  port: 8880\n  hostnames:\n    - mydomain.com\n\napi:\n  tokens: [token1, token2]\n  auth:\n    methods: [bearer, basic, body, path] # add path auth\n\nsettings:\n  http:\n    responseHeaders: # overwrite response headers\n      X-Custom: \"Lorem Ipsum Dolor\"\n\n  message:\n    scheduling: # disable\n    injecting: # disable\n    templating: # disable\n    messageTemplate: # disable\n\n    variables: # overwrite main config variables\n      number: \"+123400010\"\n      recipients: [\"+123400020\", \"group.id\", \"user.id\"]\n\n    fieldMappings: # overwrite @message from main config\n      \"@message\":\n        - field: \"msg\"\n          score: 100\n\n  access:\n    trustedIPs: # disable\n    trustedProxies: # disable\n    ipFilter: # disable\n    fieldPolicies: # disable\n    cors: # disable\n\n    endpoints: # overwrite main config endpoints\n      allowed:\n        - pattern: /v1/receive/${{ .vars.NUMBER }}\n        - pattern: /v2/send\n      blocked:\n        - pattern: /v1/about\n\n    rateLimiting:\n      limit: 100\n      period: 10h # overwrite main config period\n\n```\n\n## Contributing\n\nFound a bug? Want to change or add something?\nFeel free to open up an [issue](https://github.com/codeshelldev/secured-signal-api/issues) or create a [pull request](https://github.com/codeshelldev/secured-signal-api/pulls)!\n\n## Support\n\nHas this Repo been helpful 👍️ to you? Then consider ⭐️'ing this Project.\n\n:)\n\n## Help\n\n**Are you having problems setting up Secured Signal API?**\u003cbr/\u003e\nNo worries check out the [discussions](https://github.com/codeshelldev/secured-signal-api/discussions) tab or our [matrix chat](https://matrix.to/#/#secured-signal-api:matrix.org) and ask for help.\n\n**We are all volunteers**, so please be friendly and patient.\n\n## License\n\nThis Project is licensed under the [MIT License](./LICENSE).\n\n## Legal\n\nLogo designed by [@CodeShellDev](https://github.com/codeshelldev), All Rights Reserved.\n\nThis Project is not affiliated with the Signal Foundation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeshelldev%2Fsecured-signal-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeshelldev%2Fsecured-signal-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeshelldev%2Fsecured-signal-api/lists"}