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

# POST /otp-totp/generate

> Gere senhas de uso único TOTP ou provisione novos segredos TOTP para fluxos de autenticação de dois fatores.

## Endpoint

```
POST https://api.bunny.build/api/v1/otp-totp/generate
```

## Autenticação

| Header         | Obrigatório | Valor                        |
| -------------- | ----------- | ---------------------------- |
| `X-API-Key`    | Sim         | Sua chave de API (`bun_...`) |
| `Content-Type` | Sim         | `application/json`           |

## Visão geral

Gere senhas de uso único baseadas em tempo (TOTP conforme RFC 6238) para fluxos de autenticação de dois fatores, ou provisione novos segredos TOTP prontos para serem cadastrados em um aplicativo autenticador. Passe um `secret` existente para obter o OTP atual, ou defina `new_secret: true` para receber um novo segredo Base32 e um URI de QR code.

## Casos de uso

* Gerar o OTP atual para o segredo registrado de um usuário no servidor
* Provisionar novos segredos 2FA durante o cadastro do usuário
* Verificar se um aplicativo autenticador está configurado corretamente
* Construir fluxos 2FA personalizados sem um serviço de autenticação externo

## Detalhes

Os OTPs têm 6 dígitos e são renovados a cada 30 segundos (janela TOTP padrão). Ao provisionar um novo segredo, a resposta inclui um URI `otpauth://` compatível com Google Authenticator, Authy e aplicativos similares.

## Corpo da requisição

| Campo        | Tipo    | Obrigatório | Descrição                                                |
| ------------ | ------- | ----------- | -------------------------------------------------------- |
| `secret`     | string  | Não         | Segredo TOTP Base32 existente para gerar o OTP           |
| `new_secret` | boolean | Não         | Defina como `true` para provisionar um novo segredo TOTP |

Pelo menos um de `secret` ou `new_secret: true` deve ser fornecido.

### Exemplo — gerar OTP a partir de segredo existente

```json theme={null}
{
  "secret": "JBSWY3DPEHPK3PXP"
}
```

### Exemplo — provisionar novo segredo

```json theme={null}
{
  "new_secret": true
}
```

## Resposta

### 200 OK

| Campo        | Tipo   | Descrição                                                                  |
| ------------ | ------ | -------------------------------------------------------------------------- |
| `otp`        | string | Senha de uso único atual com 6 dígitos                                     |
| `secret`     | string | Segredo TOTP Base32 (retornado ao provisionar novo)                        |
| `uri`        | string | URI `otpauth://` para cadastro via QR code (retornado ao provisionar novo) |
| `expires_in` | number | Segundos até o OTP atual expirar                                           |

**Exemplo (segredo existente)**

```json theme={null}
{
  "otp": "123456",
  "expires_in": 18
}
```

**Exemplo (novo segredo)**

```json theme={null}
{
  "otp": "654321",
  "secret": "JBSWY3DPEHPK3PXP",
  "uri": "otpauth://totp/Bunny?secret=JBSWY3DPEHPK3PXP&issuer=Bunny",
  "expires_in": 22
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Provide either 'secret' or 'new_secret: true'"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/otp-totp/generate \
  -H "X-API-Key: bun_sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{"secret": "JBSWY3DPEHPK3PXP"}'
```