Configuration

Here is how you configure Secured Signal API

Environment Variables

Whilst being a bit restrictive environment variables are a great way to configure Secured Signal API.

Suppose you want to set a new placeholder NUMBER in your environment…

environment:
  SETTINGS__MESSAGE__VARIABLES__NUMBER: "+123400001"

This would internally be converted into settings.message.variables.number matching the config formatting.

important

Single underscores _ are removed during conversion, whereas double underscores __ convert the variable into a nested object (with __ replaced by .)

Config Files

config.yml
tokens
├── notify.yml
└── totp.yml

Config files are the recommended way to configure and use Secured Signal API, they are flexible, extensible and really easy to use.

tip

Configs also support placeholders, for example: ${{ .env.NUMBER }} or ${{ .vars.RECIPIENTS }}

• Use .vars for placeholders from variables
• and .env for environment variables

note

To change the internal config file location set CONFIG_PATH in your environment to an absolute path (default: /config/config.yml)

This example config shows all the individual settings that can be applied:

# Example Config (all configurations shown)
service:
  logLevel: info
  port: 8880
  hostnames:
    - mydomain.com

api:
  url: http://signal-api:8080
  tokens: [token1, token2]
  auth:
    methods: [bearer, basic, body]
    tokens:
      - set: [pathToken1, pathToken2]
        methods: [path]
      - set: [queryAndBodyToken]
        methods: [body, query]

settings:
  message:
    templating:
      messageTemplate: |
        You've got a Notification:
        {{ @message }} 
        At {{ @data.timestamp }} on {{ @data.date }}.
        Send using {{ .NUMBER }}.

    variables:
      number: "+123400001"
      recipients: ["+123400002", "group.id", "user.id"]
      text_mode: "${{ .env.TEXT_MODE }}"

    fieldMappings:
      "@message":
        - field: "msg"
          score: 100

  access:
    trustedIPs:
      - 192.168.1.10

    trustedProxies:
      - 172.20.0.100

    ipFilter:
      allowed:
        - 192.168.1.10
        - 192.168.2.0/24
      blocked:
        - 192.168.2.44

    endpoints:
      allowed:
        - pattern: /v2/send
        - pattern: /v1/receive/${{ .vars.NUMBER }}
      blocked:
        - pattern: /v1/about
        - pattern: /v1/receive/[^0]+
          matchType: regex

    rateLimiting:
      limit: 100
      period: 1h

    fieldPolicies:
      "@number":
        - value: "+123400003"
          action: block
        - value: "+12340000[4-9]"
          matchType: regex
          action: block

Token Configs

tokens
├── notify.yml
└── totp.yml

But wait! There is more… 😁

Token configs can be used to create per-token defined overrides and settings.

note

Create them under TOKENS_PATH (default: config/tokens/)

Here is an example:

# Example Token Config (overwrites)
service:
  logLevel: info
  port: 8880
  hostnames:
    - mydomain.com

api:
  tokens: [token1, token2]
  auth:
    methods: [bearer, basic, body, path] # add path auth

settings:
  message:
    template: # disable
    variables: # overwrite main config variables
      number: "+123400010"
      recipients: ["+123400020", "group.id", "user.id"]

    fieldMappings: # overwrite @message from main config
      "@message":
        - field: "msg"
          score: 100

  access:
    trustedIPs: # disable
    trustedProxies: # disable
    ipFilter: # disable

    endpoints: # overwrite main config endpoints
      allowed:
        - pattern: /v1/receive/${{ .vars.NUMBER }}
        - pattern: /v2/send
      blocked:
        - pattern: /v1/about

    rateLimiting:
      limit: 100
      period: 10h # overwrite main config period

    fieldPolicies: # disable