Skip to main content

Config (dev-portal.json)

The dev-portal.json file is the code that drives most of the configuration of your Zuplo Gateway. The primary uses of the dev-portal.json file are:

  • Enabling or disabling features of the Gateway
  • Setting custom values to various configuration
  • Mapping environment variables to settings
tip

The dev-portal.json file can be edited through a more rich experience in the Zuplo Portal.

Below is an example of a dev-portal.json file that is used to configure custom authentication to the Developer Portal.

{
  "enableAuthentication": true,
  "authentication": {
    "authority": "https://dev-123566.okta.com/oauth2/ausXXXXXXXXXXXX",
    "jwksUrl": "https://dev-123566.okta.com/oauth2/ausXXXXXXXXXXXX/v1/keys",
    "provider": "okta",
    "devPortalClient": {
      "clientId": "XXXXXXXXXXXX",
      "audience": "api://my-api"
    }
  }
}

Properties​

  • faviconUrl The URL to the favicon used by the developer portal
  • pageTitle The value of the <title> element used by the developer portal
  • sitePathname The path where the Developer Portal is served on your domain. Defaults to /docs.
  • enableAuthentication - If users can log in to the developer portal
  • authentication - Authentication settings
    • authority - The URL to your identity provider's OAuth endpoint
    • jwksUrl - The URL to the identity provider's JSON Web Key Set URL.
    • provider - The identity provider being used. Either auth0 or okta
    • devPortalClient

Mapping environment variables to settings​

Environment variables can be used instead of hard-coded settings inside of the dev-portal.json file. This is the best practice when setting secret values like apiKey. Using environment variables is also useful when settings change by environment. For example, if you use different OAuth Clients depending on environment.

Any whole value in the dev-portal.json file can be substituted for an environment variable. Substitution is done by setting the string value to $env(ZUPLO_PUBLIC_MY_VARIABLE_NAME) where ZUPLO_PUBLIC_MY_VARIABLE_NAME is the name of your config or secret environment variable. Variable names must start with ZUPLO_PUBLIC in order to be substituted.

Below is an example dev-portal.json file with several values substituted by environment variables.

{
  "enableAuthentication": true,
  "authentication": {
    "authority": "$env(ZUPLO_PUBLIC_OKTA_DEV_PORTAL_AUTHORITY)",
    "jwksUrl": "$env(ZUPLO_PUBLIC_OKTA_DEV_PORTAL_JWKS_URL)",
    "provider": "okta",
    "devPortalClient": {
      "clientId": "$env(ZUPLO_PUBLIC_OKTA_DEV_PORTAL_CLIENT_ID",
      "audience": "api://my-api"
    }
  }
}