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 files are the recommended way to configure and use Secured Signal API, they are flexible, extensible and really easy to use.

Config files allow YAML formatting and additionally ${ENV} to get 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:
    template: |
      You've got a Notification:
      {{@message}} 
      At {{@data.timestamp}} on {{@data.date}}.
      Send using {{.NUMBER}}.

    variables:
      number: "+123400001"
      recipients: ["+123400002", "group.id", "user.id"]

    fieldMappings:
      "@message": [{ field: "msg", score: 100 }]

  access:
    trustedIPs:
      - 192.168.1.10

    trustedProxies:
      - 172.20.0.100

    ipFilter:
      - 192.168.1.10
      - 192.168.2.0/24
      - "!192.168.2.44"

    endpoints:
      - "!/v1/about"
      - /v2/send

    rateLimiting:
      limit: 100
      period: 1h

    fieldPolicies:
      "@number":
        - value: "+123400003"
          action: block
        - value: "+123400004"
          action: block

Token Configs

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
      - "!/v1/about"
      - /v1/receive
      - /v2/send

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

    fieldPolicies: # disable