Parameters

Ampt's built-in parameter store allows developers to store the parameters in a secure way, and to use them programmatically with the params interface of Ampt SDK. All the parameters are encrypted both at transit and at rest and only decrypted during runtime.

Parameter Scopes #

Some parameters apply to all apps within an organization, while others might be specific to a particular project or application. Additionally, an application will probably use a different value of a parameter in production and development.

Organization-level parameters are defined under "Organization Settings" in the Ampt Dashboard. Every environment of every app will inherit those parameters automatically. Organization-level parameters can be overridden at the app and environment levels. For example, you can define an API key to be used for a third-party vendor as THIRD_PARTY_API_KEY and you can override this parameter for the production environment.

App-level parameters are defined for each application under App Settings. This is helpful when you need to declare a parameter that must be used by all environments of an application. For example, you can define the STRIPE KEY for the billing app, and it will be applied solely to this app's environments.

All the parameters defined at the organization and app level are inherited at the environment level and applied to the apps running in those environments. You can't define a new parameter at environment level but you can override the inherited parameters' values. For example, you can override the API keys required for your personal sandbox.

Reserved Parameters #

Ampt reserves some of the keys that are automatically populated by our runtime. The following parameters below are not allowed to be defined on the Ampt Dashboard.

Reading parameters programmatically #

Developers can access the parameters injected to the runtime by using the params interface.

javascriptCopy code
import { params } from "@ampt/sdk";
import { api } from "@ampt/api";

api("my-api")
  .router("/test-data")
  .get("/", async (event) => {
    // reading a custom parameter in an API handler
    console.log(params("KEY"));

    // reading reserved parameters is same as reading the custom parameters
    console.log(params("AMPT_URL"));

    // return all params
    const parameterList = params().list();

    // exported params are available as environment variables
    console.log(process.env.AMPT_URL);
  });

Exporting parameters as environment variables #

Developers can export parameters to an app's environment variables when required by certain frameworks or SDKs.

javascriptCopy code
import { params } from "@ampt/sdk";
// exporting at init time

params().export(); // export all parameters as environment variables
params().export("KEY"); // export specific key to process.env
params().export(["AMPT_URL", "KEY"]); // export list of keys to process.env

api("my-api")
  .router("/test-data")
  .get("/", async (event) => {
    // exported params are available as environment variables
    console.log(process.env.AMPT_URL);
  });

Parameter Groups #

For better organization, you can group parameters under a common namespace. For example, you can group all the parameters related to a third-party vendor under a common namespace like THIRD_PARTY. This will help you to easily identify and manage the parameters.

Parameter groups act the same as parameters - you can override specific parameters in a group at the app and environment levels. For example, you can override the API_KEY of the THIRD_PARTY group for the production environment, but all other parameters will be inherited from the organization or app level group.

Unlike Parameters, however, you can't export parameter groups as environment variables programmatically. Instead, you can set an "Export As" key when creating or editing a parameter group. If set, this parameter will be exported to the environment with the given name when your app starts.

To access a parameter group programmatically, you can use the params().group() interface.

javascriptCopy code
const thirdPartyCredentials = params().group("THIRD_PARTY");
const thirdPartyApiKey = thirdPartyCredentials("API_KEY");
// or
const thirdPartyApiKey = thirdPartyCredentials[API_KEY];
// or if exported as `THIRD_PARTY_API_KEY`
const thirdPartyApiKey = process.env.THIRD_PARTY_API_KEY;