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

# Rotacionar credenciais do aplicativo

> Substitua as credenciais do seu aplicativo e atualize opcionalmente nome, descrição, URIs de redirecionamento ou avatar.

Rotacionar seu aplicativo gera um novo `client_secret` e invalida o anterior imediatamente. Você só precisa enviar `client_id` e `email` para rotacionar. Qualquer outro campo que você incluir atualizará o aplicativo. Campos omitidos permanecem inalterados.

<Warning>
  O `client_secret` antigo é invalidado imediatamente após a rotação. Atualize seu aplicativo assim
  que receber as novas credenciais por e-mail.
</Warning>

## Quando rotacionar

* Seu `client_secret` foi comprometido ou perdido
* Você precisa alterar o nome, descrição ou avatar do aplicativo
* Você precisa adicionar ou remover URIs de redirecionamento

## Como funciona

A rotação usa o `client_id` e o `email` como prova de propriedade. As novas credenciais são sempre enviadas para o e-mail cadastrado no aplicativo. Esse e-mail não pode ser alterado e nunca é retornado pela API.

<Steps>
  <Step title="Envie a requisição de rotação">
    Chame `POST /v1/auth/rotate-app` com seu `client_id`, `email` e os campos que deseja atualizar.
  </Step>

  <Step title="Receba as novas credenciais por e-mail">
    Um novo `client_secret` é gerado e enviado para o e-mail cadastrado no aplicativo. O secret
    antigo é invalidado imediatamente.
  </Step>

  <Step title="Atualize seu aplicativo">
    Substitua o `client_secret` armazenado no seu aplicativo pelo novo valor.
  </Step>
</Steps>

## Rotacionar via API

Requisição mínima: apenas rotaciona as credenciais, mantém todos os dados atuais do aplicativo:

```bash theme={null}
curl -X POST https://api.vendaze.com/v1/auth/rotate-app \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "email": "voce@suaempresa.com"
  }'
```

Com atualizações opcionais: rotaciona as credenciais e atualiza o aplicativo ao mesmo tempo:

```bash theme={null}
curl -X POST https://api.vendaze.com/v1/auth/rotate-app \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "email": "voce@suaempresa.com",
    "app_name": "Minha Integração v2",
    "description": "Descrição atualizada da Minha Integração",
    "avatar_url": "https://meuapp.com/assets/logo-v2.png",
    "redirect_uris": ["https://meuapp.com/oauth/callback"]
  }'
```

**Resposta (200):**

```json theme={null}
{
  "data": {
    "app_name": "Minha Integração v2",
    "client_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "avatar_url": "https://storage.vendaze.com/assets/integrations/minhaintegracaov2.jpg",
    "message": "New credentials sent by email."
  }
}
```

O novo `client_secret` é enviado **somente por e-mail** e nunca retorna na resposta da API. Guarde-o com segurança assim que receber.

## Parâmetros da requisição

| Parâmetro       | Tipo      | Obrigatório | Descrição                                                                                                                                                      |
| --------------- | --------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`     | string    | Sim         | `client_id` atual do aplicativo a ser rotacionado.                                                                                                             |
| `email`         | string    | Sim         | E-mail cadastrado no aplicativo. Usado para verificar a propriedade. A API nunca revela qual e-mail está cadastrado. Retorna erro se o valor não corresponder. |
| `app_name`      | string    | Não         | Novo nome exibido aos usuários na tela de consentimento. Máx. 100 chars. Se omitido, o nome atual é mantido.                                                   |
| `description`   | string    | Não         | Nova descrição do que seu app faz. Máx. 500 chars. Se omitido, a descrição atual é mantida.                                                                    |
| `avatar_url`    | string    | Não         | URL HTTPS do logo do seu app. Formatos aceitos: JPEG, PNG, WebP, GIF, BMP, TIFF. Se omitido, o avatar atual é mantido.                                         |
| `redirect_uris` | string\[] | Não         | Nova lista de URIs HTTPS de redirecionamento. Substitui a lista anterior integralmente. Se omitido, a lista atual é mantida.                                   |

<Note>
  Os escopos não podem ser alterados via rotação. Eles são definidos no registro e são permanentes
  durante toda a vida útil do aplicativo. Para solicitar escopos diferentes, é necessário registrar
  um novo aplicativo com um endereço de e-mail diferente, já que cada e-mail só pode estar associado
  a um aplicativo registrado. Registrar um novo aplicativo gera um novo `client_id`, o que invalida
  todas as autorizações existentes dos usuários. Eles precisarão passar pelo fluxo de consentimento
  novamente.
</Note>

## O que muda após a rotação

| Campo            | Após a rotação                                    |
| ---------------- | ------------------------------------------------- |
| `client_secret`  | Novo valor. Enviado por e-mail. Atualize seu app. |
| `client_id`      | Não muda. Permanece o mesmo.                      |
| Nome             | Atualizado se enviado na requisição.              |
| Descrição        | Atualizada se enviada na requisição.              |
| Avatar           | Atualizado se `avatar_url` enviado na requisição. |
| URIs de redirect | Atualizadas se enviadas na requisição.            |
| Tokens ativos    | Não afetados. Sessões existentes continuam.       |

## Relacionados

* [Registre seu aplicativo](/pt/guides/register-app): registro inicial para obter suas primeiras credenciais
* [Autenticação](/pt/guides/authentication): implemente o fluxo OAuth 2.1 após atualizar suas credenciais