# Autenticación

> Cómo obtener el token con correo y contraseña, enviarlo en cada llamada, cuánto dura, las rutas públicas, actuar en nombre de otro perfil y cómo montar una cuenta de integración segura.

La API de Memberfy usa **tokens JWT**. Cambias correo y contraseña por un token y lo envías en cada llamada. El token es de una **persona** (la cuenta); lo que puede hacer depende de su rol en la comunidad de cada llamada.

## Obtener el token

```bash
curl -s -X POST https://api.memberfy.net/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"integracion@memberfy.net","password":"tu-contraseña"}'
```

Respuesta (resumida):

```json
{
  "success": true,
  "message": "Login successful.",
  "data": {
    "token": "eyJhbGciOi…",
    "member": { "id": "…", "email": "integracion@memberfy.net", "fullName": "Integración" }
  }
}
```

Guarda `data.token`.

## Usar el token

En todas las llamadas que no sean públicas:

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

Solo el token, después de `Bearer `. Junto a él, casi siempre, el [X-CommunityId](/api/x-community-id).

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

## Validez

El token vale **7 días**. No hay refresh token: cuando esté a punto de caducar, vuelve a iniciar sesión.

La API devuelve estos mensajes tal cual; algunos solo existen en portugués o en inglés.

| Situación | Respuesta |
|---|---|
| Sin token en una ruta protegida | `401` · *Authentication token is required* |
| Token no válido o caducado | `401` · *Invalid or expired token* |
| Token de alguien que no es miembro de la comunidad | `403` · *Você não é membro desta comunidade.* ("No eres miembro de esta comunidad") |
| Rol insuficiente | `403` · *Função necessária: owner ou admin. Sua função: member* ("Rol necesario: owner o admin. Tu rol: member") |

## Rutas públicas

No piden token: **inicio de sesión**, **registro**, **recuperación de contraseña** y las lecturas de lo que es **Público** en la comunidad (espacios públicos, la página de precios). En varias lecturas, el token es **opcional**: sin él, llega solo lo público; con él, llega también lo que la persona puede ver.

## Actuar en nombre de otro perfil

El propietario, los administradores y los moderadores pueden enviar `X-ProfileId: <id del perfil>` para actuar como otro perfil de la misma comunidad (para publicar en nombre de alguien del equipo, por ejemplo). Reglas:

- solo esos tres roles: *"Permissões insuficientes para usar X-ProfileId."* ("Permisos insuficientes para usar X-ProfileId");
- el perfil tiene que ser de la misma comunidad: *"Perfil no encontrado en esta comunidad."*;
- nadie actúa en nombre de un **propietario** sin ser propietario;
- actuar como otro perfil **no te presta su rol**: los permisos siguen siendo los tuyos.

## Cuenta de integración

Para una integración (un CRM, una automatización), crea un miembro solo para ella:

1. Invita a `integracion@memberfy.net` con el **rol mínimo** que necesite la integración: **Finanzas** para leer ventas; **Administrador** para crear planes y productos.
2. Guarda la contraseña en un gestor de secretos, nunca en el código.
3. Inicia sesión al principio de la ejecución y reutiliza el token hasta que caduque.
4. Si el token se filtra, cambia la contraseña de la cuenta; los tokens ya emitidos valen hasta que caduquen.

## Endpoints

| | |
|---|---|
| [`POST /api/auth/login`](/api/referencia/auth/post-auth-login) | Correo y contraseña → token |
| [`GET /api/auth/me`](/api/referencia/auth/get-auth-me) | Quién es el dueño del token |
| [`POST /api/auth/register`](/api/referencia/auth/post-auth-register) | Registro (`fullName`, `email`, `password` de al menos 8 caracteres, con una letra mayúscula, una minúscula y un número) |
| [`PUT /api/auth/change-password`](/api/referencia/auth/put-auth-change-password) | Cambiar la contraseña |
| [`POST /api/auth/recovery-password`](/api/referencia/auth/post-auth-recovery-password) | Recuperar la contraseña |
| `POST /api/auth/set-password` | Definir la contraseña con el enlace de la invitación (`id`, `token`, `password`). Responde 400 ante un token incorrecto y 410 ante un enlace usado o caducado |

## Buenas prácticas

- No pongas nunca el token en el código de una web pública: cualquiera podría leerlo.
- Usa siempre HTTPS (`https://api.memberfy.net`).
- Gestiona el `401` repitiendo el inicio de sesión una vez; si vuelve a fallar, detente y alerta.

## Relacionados

- [X-CommunityId](/api/x-community-id)
- [Roles y permisos](/conceitos/papeis-e-permissoes)
- [SDK de JavaScript](/api/sdk-js)