> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revoengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate a secret.

> ROLES: SECRET_WRITE,SECRET_ADMIN
USER: true
SERVICE ACCOUNT: true
Atomically creates an immediately active revision and disables all previous active revisions of this secret, including scheduled revisions. Retains history. Checks total and resulting active revision quotas. Returns revision metadata without the secret value. Does not rotate credentials at an external provider.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/secrets/{secretId}/rotate
openapi: 3.0.0
info:
  title: RevoEngine Platform API
  description: Official RevoEngine Platform API documentation.
  version: 1.6.2
  contact:
    name: Support
    email: support@revoengine.com
  termsOfService: https://docs.revoengine.com/tos
servers:
  - url: https://api.revoengine.com
    description: Production
security: []
tags:
  - name: Accounts
    description: Users, service accounts, API keys, status, and platform access.
    externalDocs:
      description: Identity and access guide
      url: https://docs.revoengine.com/operate/identity-and-access
  - name: Activity
    description: Snapshot-backed activity and version history.
    externalDocs:
      description: Observability guide
      url: https://docs.revoengine.com/operate/observability
  - name: Agent Memory
    description: Administrative access to durable Agent memory.
    externalDocs:
      description: Agent memory and workspaces guide
      url: https://docs.revoengine.com/ai/memory-and-workspaces
  - name: Agent Plugins
    description: Agent plugin definitions, synchronization, testing, and lifecycle.
    externalDocs:
      description: Agent plugins guide
      url: https://docs.revoengine.com/ai/plugins
  - name: Agent Terminals
    description: Terminal pairing, owner grants, access, and command activity.
    externalDocs:
      description: Connect a terminal guide
      url: https://docs.revoengine.com/ai/terminals
  - name: Agents
    description: >-
      Agent definitions, runs, sessions, inboxes, memory, tools, workspaces, and
      lifecycle.
    externalDocs:
      description: Autonomous Agents guide
      url: https://docs.revoengine.com/ai/agents
  - name: Assistant
    description: >-
      Assistant threads, messages, responses, goals, reports, sharing,
      attachments, and control.
    externalDocs:
      description: Assistant guide
      url: https://docs.revoengine.com/ai/assistant
  - name: Automation
    description: >-
      Jobs, templates, schedules, events, webhooks, execution history, and
      lifecycle.
    externalDocs:
      description: Automation guide
      url: https://docs.revoengine.com/operate/automation
  - name: Chat
    description: Collaborative chat threads, messages, reactions, uploads, and attachments.
    externalDocs:
      description: Team Chat guide
      url: https://docs.revoengine.com/operate/chat
  - name: Component deployments
    description: >-
      Custom Node.js runtime deployment attempts, readiness, activation, and
      rollback.
    externalDocs:
      description: Custom Node.js guide
      url: https://docs.revoengine.com/build/custom-nodejs
  - name: Components
    description: Components, elements, versions, validation, activation, and lifecycle.
    externalDocs:
      description: Components guide
      url: https://docs.revoengine.com/build/components
  - name: Config
    description: Instance configuration, usage, logs, and cache administration.
    externalDocs:
      description: Instance settings guide
      url: https://docs.revoengine.com/platform/instance-settings
  - name: Database Cache
    description: Instance Database cache values and statistics.
    externalDocs:
      description: Database Cache guide
      url: https://docs.revoengine.com/operate/database-cache
  - name: Database Views
    description: Database Views, previews, refreshes, exports, and controlled data actions.
    externalDocs:
      description: Database Views guide
      url: https://docs.revoengine.com/operate/database-views
  - name: Databases
    description: Database definitions, data, audits, exports, cloning, and lifecycle.
    externalDocs:
      description: Databases guide
      url: https://docs.revoengine.com/operate/databases
  - name: Endpoints
    description: >-
      Endpoint definitions, activation, validation, generated OpenAPI, and
      statistics.
    externalDocs:
      description: Endpoints guide
      url: https://docs.revoengine.com/operate/endpoints
  - name: Files
    description: Compatibility file listing, preview, download, and deletion operations.
    externalDocs:
      description: Files compatibility guide
      url: https://docs.revoengine.com/operate/files
  - name: Groups
    description: Groups, membership, avatars, and lifecycle.
    externalDocs:
      description: Groups guide
      url: https://docs.revoengine.com/operate/groups
  - name: Instance Vault
    description: Operations in the Instance Vault Platform API domain.
    externalDocs:
      description: Secrets and Vault guide
      url: https://docs.revoengine.com/operate/secrets
  - name: Me
    description: Current user profile, keys, avatar, and session information.
    externalDocs:
      description: Authentication guide
      url: https://docs.revoengine.com/developers/authentication
  - name: Preferences
    description: User and instance preference values.
    externalDocs:
      description: Platform UI guide
      url: https://docs.revoengine.com/platform/ui-tour
  - name: Role Groups
    description: Role groups, members, assigned roles, and lifecycle.
    externalDocs:
      description: Permissions guide
      url: https://docs.revoengine.com/operate/permissions
  - name: Roles
    description: Available platform roles and role details.
    externalDocs:
      description: Permissions guide
      url: https://docs.revoengine.com/operate/permissions
  - name: Search
    description: Cross-domain search over objects visible to the caller.
    externalDocs:
      description: Search and discovery guide
      url: https://docs.revoengine.com/platform/search
  - name: Secrets
    description: >-
      Secret definitions, revision history, explicit rotation, activation,
      reveal, disable, and destruction.
    externalDocs:
      description: Secrets guide
      url: https://docs.revoengine.com/operate/secrets
  - name: Share
    description: >-
      Short-lived authenticated links to supported application routes and grid
      state.
    externalDocs:
      description: Platform API share-link guide
      url: >-
        https://docs.revoengine.com/developers/platform-api#share-application-context
  - name: Storage
    description: >-
      Storage workspaces, folders, objects, upload sessions, signed access, and
      lifecycle.
    externalDocs:
      description: Storage guide
      url: https://docs.revoengine.com/operate/storage
externalDocs:
  description: Documentation
  url: https://docs.revoengine.com
paths:
  /api/v1/secrets/{secretId}/rotate:
    post:
      tags:
        - Secrets
      summary: Rotate a secret.
      description: >-
        ROLES: SECRET_WRITE,SECRET_ADMIN

        USER: true

        SERVICE ACCOUNT: true

        Atomically creates an immediately active revision and disables all
        previous active revisions of this secret, including scheduled revisions.
        Retains history. Checks total and resulting active revision quotas.
        Returns revision metadata without the secret value. Does not rotate
        credentials at an external provider.
      operationId: SecretsController_rotateSecret
      parameters:
        - name: secretId
          required: true
          in: path
          description: Secret metadata identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RotateSecretDto'
      responses:
        '201':
          description: New revision metadata without secret material.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretRevisionResponseDto'
        '400':
          description: Invalid payload or revision quota reached.
        '403':
          description: Forbidden.
        '404':
          description: Secret not found.
      security:
        - bearer: []
components:
  schemas:
    RotateSecretDto:
      type: object
      properties:
        secret:
          type: string
          minLength: 1
          description: >-
            New secret value. Creates an immediately active revision and
            disables all previous active revisions of this secret atomically.
            Previous revisions remain in history; the total revision quota still
            applies.
      required:
        - secret
    SecretRevisionResponseDto:
      type: object
      properties:
        secretDataId:
          type: string
          format: uuid
        secretId:
          type: string
          format: uuid
        active:
          type: boolean
        actDate:
          type: string
          format: date-time
        version:
          type: number
        createdBy:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        lastUpdateBy:
          type: string
          format: uuid
        lastUpdateAt:
          type: string
          format: date-time
        deletedAt:
          format: date-time
          type: string
          nullable: true
        deletedBy:
          type: string
          format: uuid
          nullable: true
      required:
        - secretDataId
        - secretId
        - active
        - actDate
        - version
        - createdBy
        - createdAt
        - lastUpdateBy
        - lastUpdateAt
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT token or API Key (sk-*).
      type: http

````