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

# Escolhendo o modo de auth

> Hosted ou federado — a decisão a tomar antes de ligar o front.

Contatos entram no seu produto de duas formas. Você escolhe por ambiente, então dá
para avaliar uma em test enquanto produção roda a outra.

<CardGroup cols={2}>
  <Card title="Hosted" icon="lock" href="/pt-br/customer-auth/hosted">
    **O UserKit é dono da conta.** Cadastro, login, verificação de e-mail e
    recuperação de senha são endpoints que você chama. Os formulários são seus; as
    regras são nossas.
  </Card>

  <Card title="Federado" icon="signature" href="/pt-br/customer-auth/federated">
    **Você já tem autenticação.** Seu servidor atesta um usuário com um HMAC sobre
    o id dele, e o UserKit confia na afirmação.
  </Card>
</CardGroup>

## Qual dos dois

|                              | Hosted                                    | Federado                |
| ---------------------------- | ----------------------------------------- | ----------------------- |
| Quem guarda a senha          | UserKit                                   | Você                    |
| Quem é dono da tela de login | Você (com nossos endpoints)               | Você (inteiramente)     |
| O que comprova identidade    | Uma senha, ou um link na caixa de entrada | Um HMAC do seu servidor |
| Bom quando                   | O UserKit é o sistema de contas           | Você já tem usuários    |

Se você está começando do zero, hosted. Se o seu produto já tem uma tabela de
usuários, federado — assim você não migra ninguém.

## Definindo

```bash theme={null}
curl -s -X PATCH $API/v1/organization/environments/{id} \
  -H "Authorization: Bearer $UK_SESSION" \
  -H "X-Organization-Id: org_4b1e…" \
  -H 'Content-Type: application/json' \
  -d '{ "auth_mode": "federated" }'
```

Exige `organization:update`. Os dois ambientes começam como `hosted`.

## Lendo isso de uma tela de login

Uma tela de login precisa saber em que modo está antes de conseguir se
renderizar, e receber isso como configuração significa que mudar o modo não faz
nada até alguém fazer deploy. Pergunte:

```bash theme={null}
curl -s $API/v1/config/uk_pk_live_…
```

```json 200 theme={null}
{
  "environment": "live",
  "auth_mode": "hosted",
  "providers": ["google"]
}
```

Público e cacheável — nenhuma chave além da publicável, nenhuma checagem de
`Origin`, então funciona a partir de um servidor renderizando a página.
`providers` lista com o que um contato de fato conseguiria entrar, então ligar o
Google no painel acende o botão sozinho. Veja
[Login social](/pt-br/customer-auth/social).

## Os modos recusam um ao outro

Os endpoints do modo em que o ambiente *não* está respondem `409` em vez de virarem
em silêncio um segundo caminho de login:

```json /v1/contact-auth/* em ambiente federado theme={null}
{
  "error": {
    "code": "environment_not_hosted",
    "message": "this environment is in federated mode; identify contacts via boot instead"
  }
}
```

```json /v1/boot com external_id, em ambiente hosted theme={null}
{
  "error": {
    "code": "environment_not_federated",
    "message": "this environment is in hosted mode; switch it to federated to identify contacts via boot"
  }
}
```

Dois logins num sistema de contas é como o mais fraco vira a porta de entrada.

<Note>
  Boot anônimo — uma chave publicável e um `anonymous_id`, sem `external_id` —
  funciona nos **dois** modos. Rastreamento de visitante e atribuição não são uma
  questão de autenticação, então nunca batem na verificação de modo.
</Note>

## O que os dois modos têm em comum

Qualquer que seja a escolha, as mesmas coisas valem.

**Contatos são contatos.** As mesmas linhas, as mesmas arestas de identidade, a
mesma atribuição, os mesmos merges. O modo decide como um contato é *comprovado*,
não o que um contato é.

**Só um link comprova um e-mail.** Nos dois modos, `email_verified` vira verdadeiro
quando uma mensagem que chegou na caixa de entrada é clicada — nunca porque um
e-mail foi passado para uma API.

**Sessões carregam `verified`.** Uma identidade comprovada emite uma
[sessão de contato](/pt-br/concepts/credentials#sessões-de-contato)
verificada; uma não comprovada emite uma sessão marcada como não verificada e
barrada de qualquer coisa por onde os dados de outra pessoa pudessem vazar.

**As respostas não enumeram.** Cadastro, magic link, reenvio e esqueci-a-senha todos
respondem `202` incondicionalmente, e o login responde um `401` uniforme, nos dois
modos.

**A lista de origens é o portão.** Todo endpoint de chave publicável que
*escreve* alguma coisa — boot, cadastro, login, magic link, social — confere a
[lista de origens permitidas](/pt-br/guides/api-keys#a-lista-de-origens-permitidas)
antes de qualquer outra coisa. As duas **leituras** públicas endereçadas por
chave, `/v1/config` e `/v1/jwks`, não conferem: elas não cunham nada e não mandam
e-mail para ninguém, e barrá-las só impediria um servidor de renderizar sua tela
de login — porque servidor nenhum manda `Origin`.

**Seu backend verifica do mesmo jeito.** Qualquer que seja o modo do ambiente, uma
sessão de contato compra um JWT de vida curta que a sua API confere offline. Veja
[Tokens de sessão](/pt-br/customer-auth/session-tokens).