Custom Rotated Secret

Akeyless supports Rotated Secrets for a growing number of services. Suppose you need to integrate with a service that is not yet natively implemented in Akeyless. In that case, you can create a custom Rotated Secret implementation that calls the service on demand to rotate secrets.

Akeyless communicates with custom Rotated Secret implementations over HTTP and delegates the rotate operation to the external services using a particular HTTP endpoint that follows a specific input/output format.

Once you have set up a custom Rotated Secret implementation, you can create a custom Rotated Secret that calls the implementation to rotate credentials.


Custom Rotated Secret implementations are completely stateless. Akeyless provides encrypted storage for any user credentials, API keys, or other secret data required by a particular implementation and provides them to the custom Rotated Secret implementation with every request.

Set Up a Custom Rotated Secret Implementation

First, you must create a Web Target in Akeyless. This target holds the target endpoint of your application (e.g., https://my.web.server/rotate endpoint).

To create a Web Target using the Akeyless CLI, run the following command:

akeyless create-web-target -n <your web target name> \
-u https://my.web.server/rotate




Custom Rotated Secret implementations should only handle requests from a known Akeyless Gateway instance. Every request made by Akeyless to a custom Rotated Secret implementation includes an AkeylessCreds header with a temporary JWT token issued and signed by Akeyless.

Use the following endpoint to verify all requests:

  "creds": "<redacted jwt token>",
  "expected_access_id": "p-1234",
  "expected_item_name": "/custom-rotated-foo",


credsA temporary JWT token issued and signed by Akeyless that is included in the AkeylessCreds header of every request.
expected_access_idThe initial access ID used for the Akeyless Gateway (not the user credentials)."p-1234"
expected_item_name(Optional) The item name of the custom Rotated Secret. This can be helpful if a single Akeyless Gateway runs multiple custom Rotated Secrets, and the custom Rotated Secret implementation should only respond to one of them."/custom-rotated-foo"

Once you've verified that the dynamic secret credentials are valid, you should implement your rotation logic. We recommend to follow the following logic:

  1. Receive the Request from the Akeyless Gateway to rotate a secret
  2. Verify that the credentials are valid using the /validate-producer-credentials endpoint
  3. Create a new value for the expected secret.
  4. Return the new secret value using the following format:

  "payload": "New Secret Value"

Lastly. revoke the old secret. We recommend expiring the old secret after a defined time defined by your internal dynamic secret. This will help avoid issues where your application is still using the old value.

Create a Custom Rotated Secret from the CLI

To create a custom Rotated Secret from the CLI, run the following command:

akeyless rotated-secret create custom \
--name <Rotated Secret name>
--gateway-url 'https://<Your-Akeyless-GW-URL:8000>' \
--target-name <Web Target item name> \
--authentication-credentials <use-user-creds> \
--password-length 16
--rotator-type <custom> \
--custom-payload <Secret payload to be sent with rotation request> \
--auto-rotate <true|false> \
--rotation-interval <1-365>


  • name: A unique name of the Rotated Secret. The name can include the path to the virtual folder where you want to create the new Rotated Secret, using slash / separators. If the folder does not exist, it will be created together with the Rotated Secret.

  • gateway-url: Akeyless Gateway Configuration Manager URL (port 8000).

  • target-name: The name of the Web Target with which the custom Rotated Secret should be associated.

  • authentication-credentials: Determines how to connect to the target.

    • use-user-creds - Use the credentials defined on the Rotated Secret item.
  • password-length: Optional, The user's password length.

  • rotator-type: The type of credentials to be rotated. For Web Target, choose:

    • custom - to rotate the password for the user specified in the Web Target.
  • custom-payload: A secret payload to be sent with a rotation request.

  • auto-rotate: Enable auto-rotation if you need to update the password regularly. If this value is set to true, specify the rotation-interval in days.

You can find the complete list of parameters for this command in the CLI Reference - Rotated Secrets section.