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

# Authentication

> How to authenticate calls to the Tarefy API

The Tarefy API uses **JWT Bearer Token**. Every protected endpoint requires the header:

```http theme={null}
Authorization: Bearer YOUR_JWT
```

## Get a token

Use `POST /v2/auth/login`:

```bash theme={null}
curl -X POST https://app.tarefy.com/nodeapi/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@company.com",
    "password": "your-password"
  }'
```

Response:

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 123,
    "nome": "Your Name",
    "email": "your-email@company.com",
    "id_conta": 42
  }
}
```

## Expiration

Tarefy JWT tokens expire in **24 hours**. When they expire, you receive:

```http theme={null}
HTTP/1.1 401 Unauthorized
{
  "message": "Unauthorized"
}
```

Just call `/auth/login` again to get a new token.

## Best practices

<Warning>
  **Never expose your token in client-side code, public repositories or logs.** Anyone with the token has full account access.
</Warning>

* **Store tokens in a secure environment** (env vars, secret manager, httpOnly cookie)
* **Use one token per integration** when possible — easier to revoke
* **Rotate** if you suspect a leak (just change the user's password)

## Persistent API tokens (coming soon)

Currently only session JWT tokens (24h) are supported. Persistent scoped API tokens are on the roadmap.

## Common errors

| Status | Message            | Cause                                    |
| ------ | ------------------ | ---------------------------------------- |
| 401    | `Unauthorized`     | Missing, malformed or expired token      |
| 401    | `Invalid token`    | Token signed with a different JWT secret |
| 402    | `Payment required` | Account plan expired or Stripe overdue   |
| 403    | `Forbidden`        | Valid token but insufficient permission  |