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

# Autenticação

> Login por device flow ou chave de API, organização ativa, logout e whoami.

A CLI suporta duas formas de autenticação, **mutuamente exclusivas por profile**: login por device flow (para uso humano interativo) ou uma chave de API (para uso sem navegador, incluindo agentes e CI). Autenticar de uma forma limpa os dados salvos da outra.

## Login por device flow

`repass login`, sem flags, inicia um **OAuth 2.0 Device Authorization Grant** (RFC 8628), o mesmo padrão usado por CLIs como a da GitHub.

<Steps>
  <Step title="Rode o login">
    ```bash theme={null}
    repass login
    ```

    A CLI imprime uma URL de verificação e um código curto, e tenta abrir seu navegador automaticamente (melhor esforço: se falhar, a URL já está impressa para você copiar).
  </Step>

  <Step title="Aprove no navegador">
    O navegador abre `https://app.repass.com.br/device` com o código pré-preenchido. Esse é o domínio de produção; em outros ambientes (local, staging) o domínio muda de acordo com onde a CLI está apontando. Faça login no painel (se ainda não estiver) e aprove o código.
  </Step>

  <Step title="A CLI conclui a sessão">
    Enquanto você aprova, a CLI faz polling em segundo plano até detectar a aprovação. Ao concluir, ela resolve a organização ativa:

    * **0 organizações** na conta → orienta finalizar o onboarding no painel.
    * **1 organização** → é ativada automaticamente.
    * **mais de uma** → em terminal interativo pergunta qual ativar; sem TTY, orienta rodar `repass org use <id|slug>` depois.

    A sessão (`token` + validade) é salva no profile local e usada como `Authorization: Bearer` em toda chamada seguinte.
  </Step>
</Steps>

```bash Saída (exemplo) theme={null}
Para continuar, acesse a URL abaixo e informe o código:

  >> https://app.repass.com.br/device <<

  Código: *** WXYZ-1234 ***

Abrindo o navegador automaticamente (se possível)...
Autenticado como Ana Silva (ana@exemplo.com) · organização ativa: Minha Loja
```

## Login com chave de API

Ambientes sem navegador (CI, servidores, agentes) usam uma chave de API em vez do device flow:

```bash theme={null}
repass login --api-key rstr_xxxxxxxxxxxxxxxx
```

Isso valida a chave contra a API e grava apenas `apiKey` no profile (limpando qualquer `token` de sessão salvo antes). Existem dois tipos de chave, com propósitos diferentes:

| Prefixo | Escopo                                                                           | Quando usar                                                                                  |
| ------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `rstr_` | Pessoal: herda o papel (`owner`/`admin`/`member`) do usuário dono na organização | Uso interativo por uma pessoa, ou automação vinculada à identidade de um operador específico |
| `rsto_` | Da organização: sem usuário associado, organização fixa no servidor              | Automação de organização (CI, integrações), onde não faz sentido atrelar a um usuário        |

<Warning>
  Toda chave de API é exibida **uma única vez** no momento da criação. Copie e guarde em local seguro, ela não pode ser recuperada depois. Nunca commite uma chave em um repositório, nem a exponha em logs ou código de frontend.
</Warning>

<Note>
  Uma chave `rsto_` já tem organização fixa no servidor: `repass org list`/`use`/`current` recusam rodar com ela ("Chave de organização tem organização fixa: não é possível listar/trocar."). Use `rstr_` (pessoal) quando precisar trocar de organização pela CLI.
</Note>

## Organização ativa

Contas com mais de uma organização precisam de uma organização ativa definida. A CLI resolve isso com o grupo `org`:

```bash theme={null}
repass org list --json
repass org use org_01J9Z3M2P0RD8K4VC1XN6YHTBE
repass org current
```

* `org list`: lista as organizações visíveis para a sessão atual.
* `org use <idOrSlug>`: troca a organização ativa (aceita id ou slug) e persiste em `activeOrganizationId` no profile.
* `org current`: mostra a organização ativa (tenta a sessão remota primeiro; cai para o cache local do profile se a chamada falhar).

## `whoami`

Confirme a qualquer momento qual credencial e organização estão em uso, especialmente antes de rodar um comando sensível:

```bash theme={null}
repass whoami
```

```text Saída (sessão) theme={null}
Nome: Ana Silva
Email: ana@exemplo.com
Organização ativa: Minha Loja
```

```text Saída (chave de organização) theme={null}
Autenticado com chave de organização (rsto_…a1b2).
Organização (cache local): org_01J9Z3M2P0RD8K4VC1XN6YHTBE
```

## `logout`

```bash theme={null}
repass logout
```

Limpa `token`/`tokenExpiresAt`/`apiKey`/`activeOrganizationId` do profile local. Se havia uma sessão de device flow, a CLI também tenta invalidá-la no servidor. Falha de rede nessa parte não impede o logout local.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Configuração" icon="gear" href="/docs/cli/configuracao">
    Profiles nomeados, variáveis de ambiente e onde a sessão fica salva.
  </Card>

  <Card title="Automação e CI" icon="robot" href="/docs/cli/automacao-ci">
    Uso não interativo com `REPASS_API_KEY` e `--yes`.
  </Card>
</CardGroup>