# Ativação de instâncias

> Como uma Central publicada se torna ativa na Plataforma Oon — estados, fluxo de ativação, campos de parametrização e variáveis injetadas pela publicação.

Toda Central `member-central` publicada é uma **instância** registrada na Central de Ativações, a raiz de confiança do Ecossistema Oon. Enquanto a instância não está ativa, o Core libera apenas o fluxo de ativação e os health checks; autenticação e CRUD ficam bloqueados.

> [!NOTE]
> No [runtime local](/docs/fundamentos/runtime-local) a instância já nasce no estado `ativa_local`, sem consultar a Central. Este fluxo só existe nos ambientes publicados.

## Estados

| Estado | Significado | O que o frontend mostra |
|---|---|---|
| `nao_ativada` | Instância registrada, aguardando código de ativação | Assistente em `/ativacao` |
| `configurando` | Ativação em andamento | Assistente em `/ativacao` |
| `ativa` | Pronta para uso | O App |
| `erro` | Falha na ativação; pode ser retomada | Assistente com "tentar novamente" |
| `suspensa` | Suspensa pela Central | `/instancia-suspensa` |
| `revogada` | Revogada pela Central | `/instancia-revogada` |
| `ativa_local` | Runtime local | O App, com o banner de desenvolvimento |

O `ActivationProvider` do frontend consulta `/ativacao/status` antes de liberar as rotas privadas, e o `ActivationGuard` leva para a página correspondente. O código de ativação fica apenas em memória e é limpo depois da conclusão.

## Fluxo

| Etapa | Endpoint | O que faz |
|---|---|---|
| Consultar | `GET /ativacao/status` | Estado da instância, sem segredos (`status`, `podeAtivar`, `podeTentarNovamente`, ambiente) |
| Parametrizar | `GET /ativacao/configuracao` | Campos de parametrização declarados pelo App |
| Validar | `POST /ativacao/validar-codigo` | Valida o código de ativação **sem consumi-lo** |
| Concluir | `POST /ativacao/concluir` | Revalida, registra a ativação na Central, cifra imediatamente a credencial da instância e marca `ativa` |
| Retomar | `POST /ativacao/tentar-novamente` | Retoma uma ativação já registrada sem exigir novo código |

As rotas de ativação têm limite de tentativas compartilhado entre réplicas. Uma ativação travada em `configurando` por tempo demais pode ser retomada.

## Campos de parametrização

Declare em `central.app.json` os parâmetros que o operador informa na ativação:

```json title="central.app.json"
{
  "activation": {
    "enabled": true,
    "configurationVersion": 1,
    "fields": []
  }
}
```

| Campo | Regra |
|---|---|
| `enabled` | Booleano; `false` desliga o fluxo de ativação |
| `configurationVersion` | Inteiro ≥ 1; aumente quando os campos mudarem |
| `fields` | Lista de campos exibidos no assistente; valores do tipo `password` e `secret` são sanitizados na configuração devolvida ao frontend |

## Credencial da instância

Ao concluir, a Central emite uma credencial própria da instância, separada do token dos usuários. Ela é cifrada com AES-256-GCM antes de ser gravada e nunca é exposta ao frontend, às APIs públicas ou aos logs. É essa identidade operacional que o Core usa nas chamadas autorizadas à Plataforma.

## Variáveis injetadas pela publicação

| Variável | Uso |
|---|---|
| `CENTRAL_ATIVACAO_URL` | URL pública da Central de Ativações |
| `CENTRAL_ATIVACAO_API_URL` | URL do backend da Central (padrão `https://central-ativacao.oonapps.online/api/`); aliases legados `CENTRAL_ATIVACAO_BACKEND_URL` e `MEUS_APPS_BACKEND_URL` |
| `APP_CODE` | Código do App no Ecossistema |
| `APP_ENVIRONMENT` | `desenvolvimento`, `homologacao` ou `producao` |
| `PUBLIC_APP_URL` | Origem pública HTTPS do App (usada nos links de convite); sem credenciais, query, fragmento ou subcaminho |
| `INSTANCE_CREDENTIAL_ENCRYPTION_KEY` | Chave AES-256-GCM da credencial da instância; obrigatória em produção |
| `AUTH_PROVIDER_TIMEOUT_MS` | Timeout das chamadas à Central (padrão 10 s) |

> [!WARNING]
> Essas variáveis são configuradas pela publicação. Não as defina à mão no App e nunca aponte a URL da API da Central para o próprio Core.

## Relacionados

```cards
[
  { "title": "Modos de runtime", "href": "/docs/fundamentos/modos-de-runtime", "description": "Local x plataforma, e os estados no frontend." },
  { "title": "Autenticação e RBAC", "href": "/docs/seguranca/autenticacao-e-rbac", "description": "Login, oon_launch, perfis e catálogo." },
  { "title": "Publicação e ambientes", "href": "/docs/operacao/publicacao", "description": "Do commit a Dev, HML e Produção." },
  { "title": "Plataforma Oon", "href": "/plataforma", "description": "Central de Ativações, Workspace e Meus Apps." }
]
```

Fonte: https://sdk.oonapps.com/docs/fundamentos/ativacao-de-instancias