Configuration

By default, this project uses a JSON configuration file. The project will look at three places in this order:

The raw contents of the CONFIG_JSON environment variable.
If the CONFIG_PATH environment variable is populated it will attempt to read a file at that path.
If neither of the above are populated it will attempt to read a file at ./config.json.

This configuration file contains secrets. Do not commit the file to your version control system or build it into Docker images.

Configuration string types

Failing to start the server due to a configuration error may be the result of formatting a JSON string value incorrectly. Here is a list of the string types that are used in the configuration file and links on how they are parsed:

Type	Description	Example attribute	Example value
Go Time Duration	A string representing a time duration.	`requestTimeout`	`1h5m2s`
Go URL	A Uniform Resource Locator (URL).	`baseURL`	`https://localhost:8080/`
UUID	128 bits encoded as a specially formatted string.	`apiKey`	`840b785c-d844-41b6-9fd0-18bef93231a6`

Default configuration

The structure of the configuration file is shown below, defaults are populated. However, some required attributes are not populated by default.

This configuration file is for a server that uses every email provider the project supports natively. If you only want to use one email provider, you can locate the appropriate Docker image or Go main package for the provider you want and omit the configuration for unused providers.

{
  "ses": {
    "awsRegion": "",
    "accessKeyID": "",
    "fromEmail": "",
    "secretKey": ""
  },
  "sendgrid": {
    "apiKey": "",
    "fromEmail": ""
  },
  "rateLimiter": {
    "burst": 5,
    "refillRate": 0
  },
  "server": {
    "adminConfig": [
      {
        "apiKey": "",
        "aud": "",
        "uuid": "",
        "serviceAccountCreateArgs": {
          "serviceLogo": "",
          "serviceName": "",
          "serviceURL": ""
        }
      }
    ],
    "baseURL": "",
    "iss": "",
    "jwks": {
      "ignoreDefault": false
    },
    "logJSON": false,
    "logLevel": "info",
    "preventRobots": {
      "method": "",
      "recaptchav3": {
        "apkPackageName": [],
        "action": [],
        "hostname": [],
        "minScore": 0.5,
        "secretKey": "",
        "templateData": {
          "buttonBypass": false,
          "buttonText": "",
          "css": "",
          "code": "",
          "htmlTitle": "",
          "instruction": "",
          "siteKey": "",
          "title": ""
        }
      }
    },
    "relativeRedirectURL": "redirect",
    "requestTimeout": "5s",
    "requestMaxBodyBytes": 1048576,
    "secretQueryKey": "secret",
    "shutdownTimeout": "1s",
    "validation": {
      "linkLifespanDefault": "1h",
      "maxLinkLifespan": "720h",
      "maxJWTClaimsBytes": 4096,
      "jwtLifespanDefault": "5m",
      "maxJWTLifespan": "720h",
      "serviceNameMinUTF8": 5,
      "serviceNameMaxUTF8": 256,
      "urlMaxLength": 2048
    }
  },
  "storage": {
    "aes256KeyBase64": "",
    "autoMigrate": false,
    "dsn": "",
    "health": "5s",
    "initialTimeout": "10s",
    "maxIdle": "4m",
    "minConns": 2,
    "plaintextClaims": false,
    "plaintextJWK": false
  }
}

SES attributes

{
  "awsRegion": "",
  "accessKeyID": "",
  "fromEmail": "",
  "secretKey": ""
}

Attribute	Description	Required
`awsRegion`	The AWS region.	Yes
`accessKeyID`	The AWS access key ID.	Yes
`fromEmail`	The email address. Then name can optionally be included. See RFC 5322. Examples: `john@example.com`, `John Doe <john@example.com>`	Yes
`secretKey`	The AWS secret key.	Yes

SendGrid attributes

{
  "apiKey": "",
  "fromEmail": ""
}

Attribute	Description	Default	Required
`apiKey`	The SendGrid API key.		Yes
`fromEmail`	The email address. Then name can optionally be included. See RFC 5322. Examples: `john@example.com`, `John Doe <john@example.com>`		Yes

Rate limit attributes

{
  "burst": 5,
  "refillRate": 0
}

Attribute	Description	Default	Required
`burst`	The token bucket burst setting. Each service has a separate token bucket rate limiter.	`5`	No
`refillRate`	The token bucket refill rate per second. Each service has a separate token bucket rate limiter. Use a value of `0` to disable rate limiting.	`0`	No

Server attributes

{
  "adminConfig": [
    {
      "apiKey": "",
      "aud": "",
      "uuid": "",
      "serviceAccountCreateArgs": {
        "serviceLogo": "",
        "serviceName": "",
        "serviceURL": ""
      }
    }
  ],
  "baseURL": "",
  "iss": "",
  "jwks": {
    "ignoreDefault": false
  },
  "logJSON": false,
  "logLevel": "info",
  "preventRobots": {
    "method": "",
    "recaptchav3": {
      "apkPackageName": [],
      "action": [],
      "hostname": [],
      "minScore": 0.5,
      "secretKey": "",
      "templateData": {
        "buttonBypass": false,
        "buttonText": "",
        "css": "",
        "code": "",
        "htmlTitle": "",
        "instruction": "",
        "siteKey": "",
        "title": ""
      }
    }
  },
  "relativeURLRedirect": "redirect",
  "requestTimeout": "5s",
  "requestMaxBodyBytes": 1048576,
  "secretQueryKey": "secret",
  "shutdownTimeout": "1s",
  "validation": {
    "linkLifespanDefault": "1h",
    "maxLinkLifespan": "720h",
    "maxJWTClaimsBytes": 4096,
    "jwtLifespanDefault": "5m",
    "maxJWTLifespan": "720h",
    "serviceNameMinUTF8": "5",
    "serviceNameMaxUTF8": "256",
    "urlMaxLength": 2048
  }
}

Attribute	Description	Default	Required
`adminConfig`	Information about admin users to create on startup.		No
`baseURL`	The base URL of the server the internet. Used to create URLs for API paths and magic link redirects. If you need a base path, be sure to include a trailing slash like: `/api/v1/`.		Yes
`iss`	The `iss` value to use when signing JWTs.		Yes
`jwks`	Information about what JWK Set should exist.		No
`logJSON`	Format logs using JSON.	false	No
`logLevel`	The level of log messages to print. `debug`, `info`, `warn`, or `error`	`info`	No
`preventRobots`	Information about how to prevent robots from following magic links.		No
`relativeURLRedirect`	The relative URL for magic link redirection.	`redirect`	No
`requestTimeout`	The timeout for incoming requests.	`5s`	No
`requestMaxBodyBytes`	The maximum number of bytes to read from a request body.	`1048576`	No
`secretQueryKey`	The URL query parameter that contains the secret for the magic link.	`secret`	No
`shutdownTimeout`	The amount of time to wait for connections to close before completely shutting down the server.	`1s`	No
`validation`	The validation configuration.		No

Admin config attributes

{
  "apiKey": "",
  "aud": "",
  "uuid": "",
  "serviceAccountCreateArgs": {
    "serviceLogo": "",
    "serviceName": "",
    "serviceURL": ""
  }
}

Attribute	Description	Required
`apiKey`	The API key to use for the admin user. Must be a UUID	No
`aud`	The `aud` value to use when signing JWTs. Must be a UUID.	No
`uuid`	The UUID of the admin user.	No
`serviceAccountCreateArgs`	The arguments to use when creating a service account for the admin user.	No

Service account create arguments attributes

{
  "serviceLogo": "",
  "serviceName": "",
  "serviceURL": ""
}

Attribute	Description	Required
`serviceLogo`	A URL to the logo to use for the service account in magic link emails. Fits into `<img src="X">`. This logo should be visible against a light or dark background as the email template adapts to the system theme.	No
`serviceName`	The name to use in email metadata like the HTML title. "You've been sent a magic link from X".	Yes
`serviceURL`	The URL to redirect to when the logo is clicked in an email.	No

JWK Set attributes

{
  "ignoreDefault": false
}

Attribute	Description	Default	Required
`ignoreDefault`	Whether to ignore the default JWK Set configuration. A value of `true` this will skip a check/creation of keys on startup.	`false`	No

Prevent Robots attributes

{
  "method": "",
  "recaptchav3": {
    "apkPackageName": [],
    "action": [],
    "hostname": [],
    "minScore": 0.5,
    "secretKey": "",
    "templateData": {
      "buttonBypass": false,
      "buttonText": "",
      "css": "",
      "code": "",
      "htmlTitle": "",
      "instruction": "",
      "siteKey": "",
      "title": ""
    }
  }
}

Attribute	Description	Default	Required
`method`	The method to use to prevent robots. Valid strings: `["", "recaptchav3"]`		No
`recaptchav3`	The reCAPTCHA v3 configuration.		No

reCAPTCHA v3 attributes

{
  "apkPackageName": [],
  "action": [],
  "hostname": [],
  "minScore": 0.5,
  "secretKey": "",
  "templateData": {
    "buttonBypass": false,
    "buttonText": "",
    "css": "",
    "code": "",
    "htmlTitle": "",
    "instruction": "",
    "siteKey": "",
    "title": ""
  }
}

Attribute	Description	Default	Required
`apkPackageName`	A set of acceptable APK package names for reCAPTCHA v3 request verification.		No
`action`	A set of acceptable actions for reCAPTCHA v3 request verification.		No
`hostname`	A set of acceptable hostnames for reCAPTCHA v3 request verification.		No
`minScore`	The minimum score needed for reCAPTCHA v3 request verification.	`0.5`	No
`secretKey`	The reCAPTCHA v3 secret key. Find this in the reCAPTCHA console.		Yes
`templateData`	The HTML template data to use for web page where reCAPTCHA v3 verification takes place.		Yes

reCAPTCHA v3 HTML template data attributes

{
  "buttonBypass": false,
  "buttonText": "",
  "css": "",
  "code": "",
  "htmlTitle": "",
  "instruction": "",
  "siteKey": "",
  "title": ""
}

Attribute	Description	Default	Required
`buttonBypass`	Recommended to be set to `true`. Whether to show a button to bypass the reCAPTCHA v3 verification. This allows a user to manually click for a redirect in the event their browser won't run JavaScript or reCAPTCHA v3 failure. There is a small, unlikely chance a security product peforming link scanning would click the button.	`false`	No
`buttonText`	The text to use for the bypass button.	`Continue`	No
`css`	The CSS to use for the reCAPTCHA v3 verification page.	Generated using Tailwind CSS	No
`code`	A smaller, shorter title to display above the main title.	`BROWSER CHECK`	No
`htmlTitle`	The HTML title to use for the reCAPTCHA v3 verification page. Not rendered on the web page itself, but visible in the browser tab.	`Magic Link - Browser Check`	No
`instruction`	Smaller text below the title displayed to the user.	`This page helps prevent robots from using magic links.`	No
`siteKey`	The reCAPTCHA v3 site key. Find this in your reCAPTCHA v3 admin console.		Yes
`title`	The title is the largest text rendered on the page visible to the user.	`Checking your browser...`	No

Validation attributes

{
  "linkLifespanDefault": "1h",
  "maxLinkLifespan": "720h",
  "maxJWTClaimsBytes": 4096,
  "jwtLifespanDefault": "5m",
  "maxJWTLifespan": "720h",
  "serviceNameMinUTF8": "5",
  "serviceNameMaxUTF8": "256",
  "urlMaxLength": 2048
}

Attribute	Description	Default	Required
`linkLifespanDefault`	The default lifespan of a magic link.	`1h`	No
`maxLinkLifespan`	The maximum lifespan of a magic link.	`720h`	No
`maxJWTClaimsBytes`	The maximum number of bytes for JWT claims.	`4096`	No
`jwtLifespanDefault`	The default lifespan of a JWT.	`5m`	No
`maxJWTLifespan`	The maximum lifespan of a JWT.	`720h`	No
`serviceNameMinUTF8`	The minimum number of UTF-8 characters for a service name.	`5`	No
`serviceNameMaxUTF8`	The maximum number of UTF-8 characters for a service name.	`256`	No
`urlMaxLength`	The maximum length of a URL.	`2048`	No

Storage attributes

{
  "aes256KeyBase64": "",
  "autoMigrate": false,
  "dsn": "",
  "health": "5s",
  "initialTimeout": "10s",
  "maxIdle": "4m",
  "minConns": 2,
  "plaintextClaims": false,
  "plaintextJWK": false
}

Attribute	Description	Default	Required
`aes256KeyBase64`	The base64 encoded 256 bit AES-GCM key to use for encrypting data like JWT claims and JWK Set assets.		Yes, unless all plaintext attributes are set to `true`
`autoMigrate`	Whether or not to perform database migrations automatically. (Recommended: `true`)	false	No, but strongly recommended
`dsn`	The DSN to use for connecting to the database.		Yes
`health`	The interval to check the database connection.	`5s`	No
`initialTimeout`	The timeout for the initial database connection.	`10s`	No
`maxIdle`	The maximum amount of time to keep a database connection idle.	`4m`	No
`minConns`	The minimum number of database connections to keep open.	`2`	No
`plaintextClaims`	Whether to store JWT claims in plaintext.	`false`	No
`plaintextJWK`	Whether to store the JWK Set assets in plaintext.	`false`	No

Want to say thanks for writing up the docs? Support the project financially? Consider becoming a GitHub Sponsor.