> ## 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.

# Permissions

> How authorization works in the Tarefy API

## Overview

Each Tarefy user has **granular permissions** within their account, configured by the administrator. These permissions determine which API endpoints the JWT token can access.

When a request is made to a protected endpoint, the API validates the token and:

* **Allows** if the user has the required permission → `2xx` response
* **Blocks** otherwise → `403 Forbidden` response

## Discovering your permissions

To find out which permissions the authenticated token has, use:

```bash theme={null}
curl https://app.tarefy.com/nodeapi/v2/users/me \
  -H "Authorization: Bearer YOUR_TOKEN"
```

The response includes a `permissions` field listing the permissions granted to the user. Use that array to decide client-side which features to enable before calling specific endpoints — avoiding unnecessary 403s.

## Handling 403 in your integration

Even with prior checks, you may still receive `403 Forbidden` (admin changes permissions, account switch, etc.). Handle it like:

```javascript theme={null}
if (res.status === 403) {
  // The user lost permission for this endpoint
  // → refresh UI / show clear message / fallback
}
```

The response body:

```json theme={null}
{
  "message": "Forbidden",
  "code": "INSUFFICIENT_PERMISSION"
}
```

## Permissions per endpoint

Every endpoint in the [API Reference](/api-reference) clearly states whether it requires a permission. Generally:

* **Read** (`GET`) — requires reading the resource
* **Write** (`POST`/`PATCH`/`PUT`) — requires editing the resource
* **Admin** — requires a specific administrative permission

Available permissions are defined by the account administrator in the Tarefy app. For a user to gain access to a specific endpoint, the administrator must grant the corresponding permission.

## Permission-related errors

| Status             | Scenario                                                                                             |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing, invalid or expired token                                                                    |
| `403 Forbidden`    | Valid token, but missing required permission                                                         |
| `404 Not Found`    | Some APIs return 404 instead of 403 when the user can't read the resource (avoids leaking existence) |

See [Errors](/essentials/errors) for the full error pattern.