# Autenticazione

> Come ottenere il token con email e password, inviarlo in ogni chiamata, quanto dura, le rotte pubbliche, agire a nome di un altro profilo e come predisporre un account di integrazione sicuro.

L'API di Memberfy usa **token JWT**. Scambi email e password con un token e lo invii in ogni chiamata. Il token appartiene a una **persona** (l'account); ciò che può fare dipende dal suo ruolo nella community di ogni chiamata.

## Ottenere il token

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

Risposta (riassunta):

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

Conserva `data.token`.

## Usare il token

In tutte le chiamate che non sono pubbliche:

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

Solo il token, dopo `Bearer `. Insieme, quasi sempre, l'[X-CommunityId](/api/x-community-id).

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

## Validità

Il token vale **7 giorni**. Non esiste un refresh token: quando sta per scadere, rifai il login.

| Situazione | Risposta |
|---|---|
| Nessun token su una rotta protetta | `401` · *Authentication token is required* |
| Token non valido o scaduto | `401` · *Invalid or expired token* |
| Token di chi non è membro della community | `403` · *Você não é membro desta comunidade.* |
| Ruolo insufficiente | `403` · *Função necessária: owner ou admin. Sua função: member* |

> [!NOTE]
> Alcuni di questi messaggi arrivano ancora in inglese o in portoghese, qualunque sia l'`Accept-Language`. Basati sullo status code, non sul testo.

## Rotte pubbliche

Non richiedono token: **login**, **registrazione**, **recupero password** e le letture di ciò che è **Pubblico** nella community (spazi pubblici, la pagina dei prezzi). In diverse letture il token è **facoltativo**: senza, arriva solo ciò che è pubblico; con il token, arriva anche ciò che la persona può vedere.

## Agire a nome di un altro profilo

Proprietari, amministratori e moderatori possono inviare `X-ProfileId: <id del profilo>` per agire come un altro profilo della stessa community (per pubblicare a nome di qualcuno del team, per esempio). Regole:

- solo questi tre ruoli: *"Permissões insuficientes para usar X-ProfileId."*;
- il profilo deve appartenere alla stessa community: *"Profilo non trovato in questa community."*;
- nessuno agisce a nome di un **proprietario** senza essere proprietario;
- agire come un altro profilo **non ne prende in prestito il ruolo**: i permessi restano i tuoi.

## Account di integrazione

Per un'integrazione (un CRM, un'automazione), crea un membro dedicato:

1. Invita `integrazione@memberfy.net` con il **ruolo minimo** di cui l'integrazione ha bisogno: **Finanza** per leggere le vendite; **Admin** per creare piani e prodotti.
2. Conserva la password in un gestore di segreti, mai nel codice.
3. Fai il login all'inizio dell'esecuzione e riutilizza il token finché non scade.
4. Se il token viene esposto, cambia la password dell'account; i token già emessi valgono fino alla scadenza.

## Endpoint

| | |
|---|---|
| [`POST /api/auth/login`](/api/referencia/auth/post-auth-login) | Email e password → token |
| [`GET /api/auth/me`](/api/referencia/auth/get-auth-me) | A chi appartiene il token |
| [`POST /api/auth/register`](/api/referencia/auth/post-auth-register) | Registrazione (`fullName`, `email`, `password` di almeno 8 caratteri, con una lettera maiuscola, una minuscola e un numero) |
| [`PUT /api/auth/change-password`](/api/referencia/auth/put-auth-change-password) | Cambiare la password |
| [`POST /api/auth/recovery-password`](/api/referencia/auth/post-auth-recovery-password) | Recuperare la password |
| `POST /api/auth/set-password` | Impostare la password dal link dell'invito (`id`, `token`, `password`). Risponde 400 per un token errato e 410 per un link già usato o scaduto |

## Buone pratiche

- Non mettere mai il token nel codice di un sito pubblico: chiunque potrebbe leggerlo.
- Usa sempre HTTPS (`https://api.memberfy.net`).
- Gestisci il `401` rifacendo il login una volta; se fallisce di nuovo, fermati e segnala.

## Correlati

- [X-CommunityId](/api/x-community-id)
- [Ruoli e permessi](/conceitos/papeis-e-permissoes)
- [SDK JavaScript](/api/sdk-js)