Parameter Creation and Management Guide

Parameters allow you to pass configuration to your application as environment variables or files. They can be set at three levels: application (applies to all scopes), dimension (applies to scopes with matching dimensions), or scope (most specific).

The order of precedence is: Scope > Dimension > Application (the most specific value wins).

Creating a Parameter

Before setting values, you must first create the parameter definition at the application level.

Important fields:

• name: Display name for the parameter

• variable: The actual environment variable name your app will use

• type: Either "environment" (environment variable) or "file" (file on disk)

• encoding: Use "plaintext" for regular values

• secret: Set to true for sensitive data (passwords, API keys)

• read_only: Set to true to restrict modifications to specific roles

  API Call:

  Method: POST
  Endpoint: /parameter
  Body: '{
    "name": "Database Password",
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "type": "environment",
    "encoding": "plaintext",
    "variable": "DB_PASSWORD",
    "secret": true,
    "read_only": false
  }'

  NP CLI:

  np parameter create --body '{
    "name": "Database Password",
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "type": "environment",
    "encoding": "plaintext",
    "variable": "DB_PASSWORD",
    "secret": true,
    "read_only": false
  }'

Setting Parameter Values

After creating a parameter, you need to set values for it. Values can be set at three levels:

Application-Level Value (applies to all scopes)

API Call:

  Method: POST
  Endpoint: /parameter/:id/value
  Body: '{
    "origin_version": 1,
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "value": "my-value",
    "dimensions": {}
  }'

NP CLI:

  np parameter value create --id <parameter_id> --body '{
    "origin_version": 1,
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "value": "my-value",
    "dimensions": {}
  }'

Dimension-Level Value (applies to scopes with matching dimensions)

API Call:

  Method: POST
  Endpoint: /parameter/:id/value
  Body: '{
    "origin_version": 1,
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "value": "development-value",
    "dimensions": {
      "environment": "development"
    }
  }'

NP CLI:

  np parameter value create --id <parameter_id> --body '{
    "origin_version": 1,
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "value": "development-value",
    "dimensions": {
      "environment": "development"
    }
  }'

Scope-Level Value (most specific, overrides all others)

API Call:

Method: POST
Endpoint: /parameter/:id/value
Body: '{
  "origin_version": 1,
  "nrn": "organization=1:account=2:namespace=3:application=4:scope=5",
  "value": "scope-specific-value",
  "dimensions": {}
}'

NP CLI:

  np parameter value create --id <parameter_id> --body '{
    "origin_version": 1,
    "nrn": "organization=1:account=2:namespace=3:application=4:scope=5",
    "value": "scope-specific-value",
    "dimensions": {}
  }'

Listing Parameters

To see all parameters for an application:

API Call:

  Method: GET
  Endpoint: /parameter?nrn=<application_nrn>

NP CLI:

  np parameter list --nrn <application_nrn>

Reading a Specific Parameter

To view a parameter's details including all its values:

API Call:

  Method: GET
  Endpoint: /parameter/:id
  Query Parameters:
    - show_secret_values=true  # Optional: requires special permissions

NP CLI:

  np parameter read --id <parameter_id>

Updating a Parameter Definition

To update a parameter's metadata (name, secret status, etc.) without changing values:

API Call:

  Method: PATCH
  Endpoint: /parameter/:id
  Body: '{
    "name": "Updated Parameter Name",
    "secret": false
  }'

NP CLI:

  np parameter patch --id <parameter_id> --body '{
    "name": "Updated Parameter Name",
    "secret": false
  }'

Deleting a Parameter Value

To remove a specific parameter value:

API Call:

  Method: DELETE
  Endpoint: /parameter/:parameterId/value/:valueId

NP CLI:

  np parameter value delete --parameter-id <parameter_id> --id <value_id>

Deleticng a Parameter

To delete a parameter completely (including all values and versions):

⚠️ Warning: This action cannot be undone.

API Call:

  Method: DELETE
  Endpoint: /parameter/:id

NP CLI:

  np parameter delete --id <parameter_id>

Important Notes

• Parameters are versioned: Every change creates a new version
• Not hot-reloaded: Changes require a new deployment to take effect
• Rollback support: Rolling back a deployment restores parameter values from that deployment
• File parameters: Limited to 1 MB, must be UTF-8 encoded text
• Environment variables: Limited to 4 KB
• Secret access: Reading secret values requires specific permissions

Common Workflow Example

1. Get application NRN (if you don't have it):

Method: GET
Endpoint: /application/:id

2. Create parameter:

Method: GET
Endpoint: /parameter/:id
  Body: '{
      "name": "Pool Size",
      "nrn": "organization=1:account=2:namespace=3:application=4",
      "type": "environment",
      "encoding": "plaintext",
      "variable": "POOL_SIZE",
      "secret": false,
      "read_only": false
  }'

3. Set application-level default:

  Method: POST
  Endpoint: /parameter/:id/value
  Body: '{
      "origin_version": 1,
      "nrn": "organization=1:account=2:namespace=3:application=4",
      "value": "100",
      "dimensions": {}
  }'

4. Override for production scope:

   Method: POST
   Endpoint: /parameter/:id/value
   Body: '{
       "origin_version": 2,
       "nrn": "organization=1:account=2:namespace=3:application=4:scope=5",
       "value": "200",
       "dimensions": {}
   }'

5. Deploy to apply changes - parameters are only applied during deployment

This guide follows the same structure as your deployment guide and covers all the operations I performed while creating your parameters!