---
sidebar_label: Accessing secret values
toc_max_heading_level: 3
doc_id: 5a90c975-b700-499e-b1cf-0552038ba1ae
description: >-
  Methods to access hidden secret parameter values in nullplatform through
  roles, approvals, or policies, including access limited to specific
  dimensions.
keywords:
  - secrets
  - security
  - permissions
  - approvals
  - policies
  - dimensions
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';


# Accessing secret values

To keep things secure, nullplatform hides secret parameter values as they’re intended to hold sensitive information. You
can still get access to these values using these methods:

- Grant the SecOps role
- Ask for approval
- Set policies

Access doesn't have to be all-or-nothing: approvals and policies can grant access to **all of a parameter's values**, or only to the values for **specific [dimensions](/docs/dimensions)**, like an environment.

## Grant the SecOps role

In nullplatform, reading **secret parameter values** requires a specific permission granted through the **SecOps role**. You can assign this role to trusted members of your organization in the **Team & Permissions** section.


> See [Authorization and roles](/docs/authorization/roles) for more on managing roles.


## Ask for approval

Users who don't have the `SecOps` role can request access to secret values through approvals. You can request access from the parameter's page in the dashboard when you try to reveal its secret values.


#### What happens when access is requested:

- Access is limited to the **dimensions of the request**. An approval for `environment: development` lets you reveal only the values that match that dimension, while a request without dimensions covers **every value** of the parameter.
- Access applies to **all versions** of the values it covers.
- Once approved, access remains valid for **24 hours**. This duration is controlled by the `allowed_time_to_execute` field on the approval action.
- If no approver responds within **3 days**, the request expires. This duration is controlled by the `time_to_reply` field on the approval action.

Both windows are configured on the approval action itself. You can adjust them when [sending a POST request to create](/docs/api/approval-action-create) or [sending a PATCH request to update](/docs/api/approval-action-update) the approval action. For more on how these windows affect request statuses, see [Approval request lifecycle](/docs/approvals/approval-requests#expiration-windows).

<Tabs
defaultValue="secret-access-cli"
values={[
{ label: 'CLI', value: 'secret-access-cli' },
{ label: 'cURL', value: 'secret-access-curl' },
]}>

<TabItem value="secret-access-cli">

```bash
np approval action create
  --body '{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "entity": "parameter",
    "action": "parameter:read-secrets",
    "time_to_reply": 259200000,
    "allowed_time_to_execute": 86400000
  }'
```

</TabItem>
<TabItem value="secret-access-curl">

```bash
curl -L -X POST 'https://api.nullplatform.com/approval/action' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "entity": "parameter",
  "action": "parameter:read-secrets",
  "time_to_reply": 259200000,
  "allowed_time_to_execute": 86400000
}'
```

</TabItem>
</Tabs>

In this example, approvers have 3 days to respond, and access remains valid for 24 hours after approval.

> To configure your organization to use approvals for this use case, refer to the [Approvals docs](/docs/approvals/).


## Reveal values for specific dimensions

When you read a parameter with `show_secret_values=true`, add the `dimensions` query parameter to choose which values to reveal. Only the values matching those dimensions come back with their content; every other value stays hidden:

```bash
curl -L 'https://api.nullplatform.com/parameter/1234?show_secret_values=true&dimensions=environment:production' \
-H 'Authorization: Bearer <token>'
```

The response keeps the full list of values and reveals only the matching ones:

```json
{
  "id": 1234,
  "name": "DATABASE_PASSWORD",
  "secret": true,
  "values": [
    {
      "value": "my-production-secret",
      "dimensions": { "environment": "production" }
    },
    {
      "value": null,
      "dimensions": { "environment": "development" }
    }
  ]
}
```

A value matches based on the dimensions it was created with, and values applied to a scope match through that scope's dimensions. See [Parameter levels](/docs/parameters#parameter-levels-application-dimension-and-scope) for how values target applications, dimensions, and scopes.

:::note
An approval for specific dimensions only covers reveals for those dimensions. To reveal every value at once (a request without `dimensions`), you need an approval that covers the whole parameter, or the permission granted through the SecOps role.
:::


## Set a policy

Policies let you automatically **approve, deny, or require manual approval** for access requests based on flexible,
rule-based conditions. These rules can consider both user attributes (e.g., their role in the organization) and
contextual factors (e.g., whether the application handles sensitive data).

:::note 
All requests to access secrets are **audited**, even if they’re automatically approved or rejected by a policy.
:::



#### Use case: Allow managers to access values for non-sensitive apps

You can configure a policy that automatically approves requests from managers, but only for applications that don’t
handle sensitive information.

Create this policy by making a [POST create a policy request](/docs/api/policy-create) or using the nullplatform CLI.


<Tabs
defaultValue="policy-cli"
values={[
{ label: 'CLI', value: 'policy-cli' },
{ label: 'cURL', value: 'policy-curl' },
]}>
<TabItem value="policy-cli">

```bash
np approval policy create
  --body '{
  "nrn": "organization=1:account=2:namespace=3:application=4",   // Specifies where the policy applies.
  "name": "Allow manager to access values for non-sensitive apps",
  "conditions": {
    "user.metadata.ic_level": { "$gte": 3 },
    "application.metadata.has_sensitive_info": { "$eq": false }
  }
}
```
</TabItem>
<TabItem value="policy-curl">

```bash
curl -L -X POST 'https://api.nullplatform.com/approval/policy' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "nrn": "organization=1:account=2:namespace=3:application=4",   // Specifies where the policy applies.
  "name": "Allow manager to access values for non-sensitive apps",
  "conditions": {
    "user.metadata.ic_level": { "$gte": 3 },
    "application.metadata.has_sensitive_info": { "$eq": false }
  }
}
```
</TabItem>
</Tabs>


#### Use case: Auto-approve lower environments, require approval for production

Access requests carry the dimensions being revealed, so a single policy can decide the outcome per environment: lower environments get approved automatically, while production requests wait for a manual review.

First, create (or update) the approval action so policy results drive the outcome. Setting `dimensions` to `{}` makes the action govern requests for any dimensions:

<Tabs
defaultValue="env-action-cli"
values={[
{ label: 'CLI', value: 'env-action-cli' },
{ label: 'cURL', value: 'env-action-curl' },
]}>

<TabItem value="env-action-cli">

```bash
np approval action create
  --body '{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "entity": "parameter",
    "action": "parameter:read-secrets",
    "dimensions": {},
    "on_policy_success": "approve",
    "on_policy_fail": "manual"
  }'
```

</TabItem>
<TabItem value="env-action-curl">

```bash
curl -L -X POST 'https://api.nullplatform.com/approval/action' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "entity": "parameter",
  "action": "parameter:read-secrets",
  "dimensions": {},
  "on_policy_success": "approve",
  "on_policy_fail": "manual"
}'
```

</TabItem>
</Tabs>

Then create a policy that passes only for the environments allowed to auto-approve. Use the environment values defined in your organization:

<Tabs
defaultValue="env-policy-cli"
values={[
{ label: 'CLI', value: 'env-policy-cli' },
{ label: 'cURL', value: 'env-policy-curl' },
]}>

<TabItem value="env-policy-cli">

```bash
np approval policy create
  --body '{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "name": "Auto-approve secret access in lower environments",
    "conditions": {
      "dimensions.environment": { "$in": ["development", "staging"] }
    }
  }'
```

</TabItem>
<TabItem value="env-policy-curl">

```bash
curl -L -X POST 'https://api.nullplatform.com/approval/policy' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "name": "Auto-approve secret access in lower environments",
  "conditions": {
    "dimensions.environment": { "$in": ["development", "staging"] }
  }
}'
```

</TabItem>
</Tabs>

Finally, [associate the policy with the action](/docs/approvals/associate-policy-with-action). From then on, a request to reveal a `development` value is approved automatically with no human step, while a request for a `production` value stays pending until an approver responds.

:::warning
Write auto-approve conditions as an **allowlist** of the environments you permit, like the `$in` above. An exclusion such as `"dimensions.environment": { "$ne": "production" }` also passes for requests that don't specify any dimensions, which would automatically approve access to every value of the parameter — including production.
:::

> Refer to the [Policies docs](/docs/approvals/policies) for more info.