---
title: "Document Engine secrets rotation | Nutrient"
canonical_url: "https://www.nutrient.io/guides/document-engine/management/secrets-rotation/"
md_url: "https://www.nutrient.io/guides/document-engine/management/secrets-rotation.md"
last_updated: "2026-05-30T02:20:01.233Z"
description: "Document Engine offers the following options for authentication:."
---

# Secrets rotation

Document Engine offers the following options for authentication:

- Dashboard password — Used to access the [Nutrient Dashboard](https://www.nutrient.io/guides/document-engine/management/dashboard.md).

- Secret keybase — Used for generating secret keys for the purposes of authentication.

- Public key for authenticating JWT payloads — Used for [client authentication](https://www.nutrient.io/guides/document-engine/viewer/client-authentication.md).

Collectively, these options are referred to as secrets.

## Secrets management

You can configure secrets using environmental variables. However, this approach has the following disadvantages:

- You can’t change secrets during runtime.

- You can’t use more than one valid secret.

- You need to restart Document Engine.

Document Engine provides an alternative mechanism for managing secrets: There’s always a “current” version of a secret that never expires and you can only change this current version using secret rotation. Next to the current version, you can have other secrets, but the non-current secrets need to have an expiration date.

By default, secrets are sourced from the following environmental variables:

- `JWT_PUBLIC_KEY`

- `SECRET_KEY_BASE`

- `DASHBOARD_PASSWORD`

To change this behavior, set the `REPLACE_SECRETS_FROM_ENV` configuration option to `false`. In this case, current secrets are only sourced from environmental variables if the secrets aren’t yet set via the API. `REPLACE_SECRETS_FROM_ENV` must be set to `false` to enable secret rotation. Otherwise, secrets set via the API are replaced on every restart.

Secrets can be managed via the [secrets API](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Secrets). The secret APIs expects the secret `:type`, which can be `jwt`, `dashboard_password`, or `secret_key_base`.

## Adding a new secret

To add a new secret, use the following request:

```json

POST /api/secrets/:type
Content-Type: application/json
Authorization: Token token="<secret token>"

{
  "secret": "my new secret string",
  "expiresAt": "2023-01-01T12:00:00.000000Z"
}

```

The `secret` field is the new secret. `expiresAt` sets the expiration date for the secret. The date and time are in UTC in [ISO 8601 format](https://www.iso.org/iso-8601-date-and-time-format.html).

## Listing secrets

To list the IDs and expiry dates of existing secrets, use the following request:

```json

GET /api/secrets/:type
Authorization: Token token="<secret token>"

```

An example response is the following:

```json

[
  {
    "id": 1,
    "expiresAt": null
  },
  {
    "id": 2,
    "expiresAt": "2023-01-01T12:00:00.000000Z"
  },...
]

```

Only non-expired secrets are returned. For the current secret, the `expiresAt` field is `null`.

## Rotating secrets

Current secrets don’t expire. To change current secrets, rotate them using the request below:

```json

POST /api/secrets/:type/rotate
Content-Type: application/json
Authorization: Token token="<secret token>"

{
  "secret": "my new secret string"
}

```

## Expiring existing secrets

To change the expiration date of secrets other than the current one, use the request below:

```json

PATCH /api/secrets/:type/:id
Content-Type: application/json
Authorization: Token token="<secret token>"

{
  "expiresAt": "2023-01-01T12:00:00.000000Z"
}

```
---

## Related pages

- [Built-in dashboard](/guides/document-engine/management/dashboard.md)