---
title: "Re-mint the subscription signing secret (human workspace owner only)"
method: POST
path: "/v1/apps/{id}/install/rotate-secret"
tags: ["Apps"]
---

# Re-mint the subscription signing secret (human workspace owner only)

`POST /v1/apps/{id}/install/rotate-secret`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/apps/{id}/install/rotate-secret`
- Auth: HTTP bearer

The plaintext is in the response ONCE; the rows re-prove the endpoint before anything is delivered under the new secret.

## Path parameters

- `id` string, uuid, required

## Response `200`

Rotated.

- object
  - `subscription_secret` string
  - `install` AppInstall: The binding between one workspace and one external service (Apps spec B7.1). Not versioned and never part of the manifest: it holds the ids that exist in one deployment only (service key, OAuth client, URL, origin).
    - `app_id` string, uuid
    - `status` 'installed' | 'suspended' | 'uninstalled'
    - `service_api_key_id` string, uuid, nullable: The workspace key the service authenticates with; null once revoked.
    - `oauth_client_id` string, uuid, nullable: The pre-consented OAuth public client the surface exchanges a session code for.
    - `surface_url` string, nullable
    - `allowed_origin` string, nullable: Exact https origin (scheme + host + optional port), no wildcard, no path.
    - `installed_by` string, nullable
    - `installed_at` string, date-time, nullable
    - `suspended_at` string, date-time, nullable
    - `suspended_reason` string, nullable: 'key_revoked' when the service key was revoked; otherwise the owner's reason.
    - `last_seen_at` string, date-time, nullable
    - `uninstalled_at` string, date-time, nullable
    - `approved_version` integer, nullable: The manifest version this install's grants, subscriptions and bindings were last synced against (§B13.2).
    - `approved_at` string, date-time, nullable
    - `approved_by` string, nullable
    - `pending_approval_version` integer, nullable: Set when a publish or hosted refresh parked a newer version on this install; while set the install is fail-closed (no embedded session, no run start, no decision-task offer, no delivery) until `POST .../install/approve`.
    - `subscriptions` AppSubscription[]
      - `id` string, uuid
      - `event_type` string
      - `match` object
      - `endpoint_url` string
      - `status` 'pending_verification' | 'active' | 'paused' | 'suspended' | 'revoked'
      - `failure_count` integer
      - `last_delivery_at` string, date-time, nullable
      - `verified_at` string, date-time, nullable
    - `bindings` AppInstallSlotBinding[]: What each requirement slot of the manifest was bound to at install.
      - `alias` string
      - `kind` string: AppResourceType of the bound resource.
      - `resource_id` string, uuid
      - `bound_at` string, date-time
  - `subscriptions` AppInstallSubscriptionsState: What an install/approve/verify/rotate call reports about the install's subscription rows as a whole.
    - `status` 'pending_verification' | 'active' | 'paused' | 'suspended' | 'revoked', nullable: The status every row of the install carries, or null when it subscribes to nothing.
    - `verified` boolean
    - `reason` string: Machine reason from the endpoint-ownership challenge when verified is false.
    - `count` integer
  - `warning` string

## Other responses

- `403`: The API key does not have the required scope.
- `404`: The requested resource was not found.
- `409`: The request conflicts with the current resource state.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)