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

# Rotate App Secret

> Replace an app's App Secret and get the new one.

Issues a new App Secret for one sandbox or production app and returns it. The previous App Secret stops working immediately, so requests that still use it return `401`. Update your backend with the new secret right after this call.

The new App Secret is returned only in this response. No other endpoint returns it, so store it when you receive it. If you lose an App Secret, or it leaks, rotate it.

## Headers

**Authorization** `string` *required*

`Bearer sk_workspace_...`, a Workspace API key of the organization that owns the app. See [Workspace API](https://docs.hopae.com/v2/api-reference/workspace/introduction.md).

**Idempotency-Key** `string`

A unique key for this request, up to 255 characters. If you retry with the same key within 24 hours, you get the stored response with `Idempotency-Replayed: true`, and the App Secret is not rotated a second time. See [Request behavior](https://docs.hopae.com/v2/api-reference/workspace/introduction.md#request-behavior).

## Path Parameters

**appId** `string` *required*

The app ID returned by Create App or List Apps.

## Response

`201 Created` with the new App Secret.

**appSecret** `string` *required*

The app's new App Secret. Use it with the app ID for Basic auth on the verification API and as the OIDC `client_secret`. See [Authentication](https://docs.hopae.com/v2/api-reference/authentication.md).

## Errors

Besides the authentication and subscription errors that every route can return (see [Workspace API](https://docs.hopae.com/v2/api-reference/workspace/introduction.md#authentication-and-base-url)), this endpoint returns:

| HTTP | Code | When |
| :- | :- | :- |
| 400 | `VALIDATION_INVALID_PARAMETER` | `Idempotency-Key` is longer than 255 characters |
| 403 | `AUTH_FORBIDDEN` | The app belongs to another organization |
| 404 | `RESOURCE_NOT_FOUND` | Unknown app, or the app was deleted |
| 409 | `RESOURCE_CONFLICT` | The app has no App Secret to rotate |
| 409 | `IDEMPOTENCY_REQUEST_IN_PROGRESS` | An earlier request with the same `Idempotency-Key` is still running |

```bash cURL theme={null}
curl --request POST \
  --url 'https://api.hopae.com/connect/v2/apps/{appId}/rotate-app-secret' \
  --header 'Authorization: Bearer sk_workspace_...' \
  --header 'Idempotency-Key: 9a1e6c3b-52d7-4f0a-8b1c-7e4d2f6a0c35'
```

```json theme={null}
{
  "appSecret": "5b1f0c9a7d3e4f6a8b2c1d0e9f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.