Authentication

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

Authorization: Bearer YOUR_JWT

Get a token

Use POST /v2/auth/login:

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:

{
  "status": true,
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

The token is a JWT. Its payload carries the user id, account id and permission level — there is no separate user object in the response.

Errors

Failures return the proper HTTP status and a machine-readable code:

{
  "status": false,
  "code": "AUTH_INVALID_CREDENTIALS",
  "message": "Por favor, informar e-mail e senha válidos."
}

Status	`code`	Meaning
400	`AUTH_CAPTCHA_FAILED`	Captcha (Cloudflare Turnstile) check failed
401	`AUTH_INVALID_CREDENTIALS`	Wrong email or password, or the user is inactive
403	`AUTH_EMAIL_NOT_VERIFIED`	Signup exists but the email was never confirmed
429	`AUTH_ACCOUNT_LOCKED`	Too many failed attempts; retry after `retryAfterSeconds`
429	`RATE_LIMITED`	Too many requests from this IP; retry after `retryAfterSeconds`

Branch on code, never on message — messages are localized and may change.

Expiration

HTTP/1.1 401 Unauthorized
{
  "message": "Unauthorized"
}

Call /v2/auth/login again to get a new token.

For server-to-server integrations, prefer an API token over signing in with a user’s password. Create one in the app under Settings → API Tokens: you choose its permission level, it can be revoked at any time, and it is not tied to someone’s password. API tokens do not expire unless you set an expiration date.

Best practices

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

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

Introduction

Concepts

Guias de integração

Authentication

Get a token

Errors

Expiration

Best practices

Persistent API tokens (coming soon)

Common errors

​Get a token

​Errors

​Expiration

​Best practices

​Persistent API tokens (coming soon)

​Common errors

Get a token

Errors

Expiration

Best practices

Persistent API tokens (coming soon)

Common errors