# Authentication

> How to get a token with email and password, send it on every call, how long it lasts, the public routes, acting on behalf of another profile and how to set up a safe integration account.

The Memberfy API uses **JWT tokens**. You exchange an email and password for a token and send it on every call. The token belongs to a **person** (the account); what they can do depends on their role in the community of each call.

## Get the token

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

Response (abridged):

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

Keep `data.token`.

## Use the token

On every call that isn't public:

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

Just the token, after `Bearer `. Almost always together with [X-CommunityId](/api/x-community-id).

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

## Lifetime

The token is valid for **7 days**. There is no refresh token: when it's close to expiring, sign in again.

| Situation | Response |
|---|---|
| No token on a protected route | `401` · *Authentication token is required* |
| Invalid or expired token | `401` · *Invalid or expired token* |
| Token of someone who isn't a member of the community | `403` · *Você não é membro desta comunidade.* (you are not a member of this community) |
| Insufficient role | `403` · *Função necessária: owner ou admin. Sua função: member* (required role: owner or admin; your role: member) |

## Public routes

These don't need a token: **sign-in**, **sign-up**, **password recovery** and reads of what is **Public** in the community (public spaces, the pricing page). On many reads the token is **optional**: without it, you get only what is public; with it, you also get what that person can see.

## Acting on behalf of another profile

Owners, admins and moderators can send `X-ProfileId: <profile id>` to act as another profile in the same community (to post on behalf of someone on the team, for example). Rules:

- only those three roles: *"Permissões insuficientes para usar X-ProfileId."* (insufficient permissions to use X-ProfileId);
- the profile has to be in the same community: *"Profile not found in this community."*;
- nobody acts on behalf of an **owner** without being an owner;
- acting as another profile **doesn't lend you their role**: the permissions are still yours.

## Integration account

For an integration (a CRM, an automation), create a member just for it:

1. Invite `integration@memberfy.net` with the **minimum role** the integration needs: **Finance** to read sales; **Admin** to create plans and products.
2. Keep the password in a secrets vault, never in the code.
3. Sign in at the start of each run and reuse the token until it expires.
4. If the token leaks, change the account's password; tokens already issued remain valid until they expire.

## Endpoints

| | |
|---|---|
| [`POST /api/auth/login`](/api/referencia/auth/post-auth-login) | Email and password → token |
| [`GET /api/auth/me`](/api/referencia/auth/get-auth-me) | Who owns the token |
| [`POST /api/auth/register`](/api/referencia/auth/post-auth-register) | Sign-up (`fullName`, `email`, `password` with at least 8 characters, an uppercase letter, a lowercase letter and a number) |
| [`PUT /api/auth/change-password`](/api/referencia/auth/put-auth-change-password) | Change the password |
| [`POST /api/auth/recovery-password`](/api/referencia/auth/post-auth-recovery-password) | Recover the password |
| `POST /api/auth/set-password` | Set the password from the invite link (`id`, `token`, `password`). Answers 400 for a wrong token and 410 for a used or expired link |

## Good practices

- Never put the token in the code of a public website: anyone could read it.
- Always use HTTPS (`https://api.memberfy.net`).
- Handle a `401` by signing in again once; if it fails again, stop and raise an alert.

## Related

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