# Autenticação

> Como obter o token com e-mail e senha, enviá-lo em cada chamada, quanto tempo ele vale, as rotas públicas, agir em nome de outro perfil e como montar uma conta de integração segura.

A API da Memberfy usa **tokens JWT**. Você troca e-mail e senha por um token e o envia em cada chamada. O token é de uma **pessoa** (a conta); o que ela pode fazer depende do papel dela na comunidade de cada chamada.

## Obter o token

```bash
curl -s -X POST https://api.memberfy.net/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"integracao@memberfy.net","password":"sua-senha"}'
```

Resposta (resumida):

```json
{
  "success": true,
  "message": "Login successful.",
  "data": {
    "token": "eyJhbGciOi…",
    "member": { "id": "…", "email": "integracao@memberfy.net", "fullName": "Integração" }
  }
}
```

Guarde `data.token`.

## Usar o token

Em todas as chamadas que não forem públicas:

```
Authorization: Bearer <token>
```

Só o token, depois de `Bearer `. Junto, quase sempre, o [X-CommunityId](/api/x-community-id).

```bash
curl -s https://api.memberfy.net/api/auth/me \
  -H "Authorization: Bearer $TOKEN"
```

## Validade

O token vale **7 dias**. Não há refresh token: perto de expirar, faça login de novo.

| Situação | Resposta |
|---|---|
| Sem token numa rota protegida | `401` · *Token de autenticação é obrigatório* |
| Token inválido ou expirado | `401` · *Token inválido ou expirado* |
| Token de quem não é membro da comunidade | `403` · *Você não é membro desta comunidade.* |
| Papel insuficiente | `403` · *Função necessária: owner ou admin. Sua função: member* |

## Rotas públicas

Não pedem token: **login**, **cadastro**, **recuperação de senha** e as leituras do que é **Público** na comunidade (espaços públicos, a página de preços). Em várias leituras, o token é **opcional**: sem ele, vem só o que é público; com ele, vem também o que a pessoa pode ver.

## Agir em nome de outro perfil

Proprietários, administradores e moderadores podem enviar `X-ProfileId: <id do perfil>` para agir como outro perfil da mesma comunidade (para publicar em nome de alguém da equipe, por exemplo). Regras:

- só esses três papéis: *"Permissões insuficientes para usar X-ProfileId."*;
- o perfil precisa ser da mesma comunidade: *"Perfil não encontrado nesta comunidade."*;
- ninguém age em nome de um **proprietário** sem ser proprietário;
- agir como outro perfil **não empresta o papel dele**: as permissões continuam sendo as suas.

## Conta de integração

Para uma integração (um CRM, uma automação), crie um membro só para ela:

1. Convide `integracao@memberfy.net` com o **papel mínimo** de que a integração precisa: **Financeiro** para ler vendas; **Administrador** para criar planos e produtos.
2. Guarde a senha num cofre de segredos, nunca no código.
3. Faça login no início da execução e reutilize o token até expirar.
4. Se o token vazar, troque a senha da conta; os tokens já emitidos valem até expirar.

## Endpoints

| | |
|---|---|
| [`POST /api/auth/login`](/api/referencia/auth/post-auth-login) | E-mail e senha → token |
| [`GET /api/auth/me`](/api/referencia/auth/get-auth-me) | Quem é o dono do token |
| [`POST /api/auth/register`](/api/referencia/auth/post-auth-register) | Cadastro (`fullName`, `email`, `password` com pelo menos 8 caracteres, uma letra maiúscula, uma minúscula e um número) |
| [`PUT /api/auth/change-password`](/api/referencia/auth/put-auth-change-password) | Trocar a senha |
| [`POST /api/auth/recovery-password`](/api/referencia/auth/post-auth-recovery-password) | Recuperar a senha |
| `POST /api/auth/set-password` | Definir a senha pelo link do convite (`id`, `token`, `password`). Responde 400 para um token errado e 410 para um link usado ou vencido |

## Boas práticas

- Nunca ponha o token no código de um site público: qualquer pessoa o leria.
- Use HTTPS sempre (`https://api.memberfy.net`).
- Trate o `401` refazendo o login uma vez; se falhar de novo, pare e alerte.

## Relacionados

- [X-CommunityId](/api/x-community-id)
- [Papéis e permissões](/conceitos/papeis-e-permissoes)
- [SDK JavaScript](/api/sdk-js)