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

# Permission Roles and Access Control in CA Colombia

> CA Colombia API uses bitfield-based permission roles. Learn what each role grants, which endpoints require elevated permissions, and how access is enforced.

CA Colombia's API enforces access control through a **bitfield permission system**. Every authenticated session carries a `permissions` value — a decimal string encoding a set of permission flags. Each flag represents a role or capability, and the API checks these flags on every request that requires elevated access. Understanding which permissions are required where will help you predict exactly what your integration can and cannot do.

## How Bitfield Permissions Work

Permissions are stored as a 64-bit integer encoded as a decimal string (e.g. `"2"`, `"32"`, `"128"`). Each bit position corresponds to a specific role or capability. A user holds a permission if the corresponding bit is set in their `permissions` value.

When your session token is issued, your permission flags are derived from your Discord roles in the CA Colombia server. They are re-evaluated every time your Discord data is refreshed.

```json theme={null}
{
  "userId": "1234567890123456789",
  "permissions": "34",
  "...": "..."
}
```

<Note>
  The `permissions` field is always a string, not a number. Parse it with your language's big-integer or bitwise utilities to check individual flags. In JavaScript, use `BigInt("34")` before performing bitwise operations.
</Note>

***

## Permission Roles

The following roles are defined in the platform. Multiple roles can be combined — a user may hold several simultaneously.

| Role                       | Bit       | Description                                                                                                                           |
| -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVICE_ADMINISTRATOR`    | `1 << 0`  | Full administrative access. Implicitly passes all permission checks, regardless of what the endpoint requires. Bypasses rate limits.  |
| `USER`                     | `1 << 1`  | Standard authenticated user. Required for all basic authenticated endpoints such as reading your own profile, characters, and wallet. |
| `DEVELOPER`                | `1 << 2`  | Developer-level access. Implicitly passes all permission checks and bypasses rate limits.                                             |
| `BOT`                      | `1 << 3`  | Identifies the caller as an automated bot. Bypasses rate limits on supported endpoints.                                               |
| `LAW_ENFORCEMENT`          | `1 << 4`  | In-game law enforcement role. Grants access to law enforcement-specific endpoints.                                                    |
| `STAFF`                    | `1 << 5`  | General staff access. Allows viewing and moderating content across users.                                                             |
| `ADMINISTRATOR`            | `1 << 6`  | Senior administrator access. Required for direct wallet write operations and other sensitive mutations.                               |
| `ADMINISTRATOR_CHIEF`      | `1 << 7`  | Chief administrator. Senior-tier administrative access.                                                                               |
| `MODERATOR`                | `1 << 8`  | Moderation access. Allows moderation actions on platform content.                                                                     |
| `MODERATOR_CHIEF`          | `1 << 9`  | Chief moderator. Grants access to staff review endpoints alongside `ADMINISTRATOR` and `DEVELOPER`.                                   |
| `INTERNAL_AFFAIRS`         | `1 << 10` | Internal affairs role for reviewing staff conduct.                                                                                    |
| `STAFF_MANAGER`            | `1 << 11` | Manages staff members and their periods.                                                                                              |
| `MEMBERSHIP`               | `1 << 12` | Platform membership. Grants an additional character slot.                                                                             |
| `BOOSTER`                  | `1 << 13` | Server booster. Grants an additional character slot.                                                                                  |
| `MEMBER_EXCLUSIVE_3_YEARS` | `1 << 14` | Exclusive role for members with 3 years on the platform.                                                                              |
| `MEMBER_EXCLUSIVE_2_YEARS` | `1 << 15` | Exclusive role for members with 2 years on the platform.                                                                              |
| `MEMBER_EXCLUSIVE_1_YEAR`  | `1 << 16` | Exclusive role for members with 1 year on the platform.                                                                               |
| `TESTER`                   | `1 << 17` | Tester access for pre-release features.                                                                                               |

<Tip>
  `SERVICE_ADMINISTRATOR` and `DEVELOPER` are **superuser** roles — they pass every permission check automatically, regardless of what specific flag an endpoint requires. If your integration holds one of these roles, you will never receive a permission-related `401` or `403` from the API.
</Tip>

***

## Rate Limit Bypass

Certain roles are exempt from the standard API rate limits:

| Role                    | Rate Limit Bypass |
| ----------------------- | ----------------- |
| `SERVICE_ADMINISTRATOR` | ✅ Yes             |
| `DEVELOPER`             | ✅ Yes             |
| `BOT`                   | ✅ Yes             |
| All others              | ❌ No              |

If your integration is a bot or automated service and you are experiencing rate limiting, contact a platform administrator to request the `BOT` role for your account.

***

## Endpoint Permission Requirements

Most endpoints require only the base `USER` permission. The following endpoints have elevated requirements:

| Endpoint                                                   | Required Permission                                 | Match   |
| ---------------------------------------------------------- | --------------------------------------------------- | ------- |
| `POST /v1/banks`                                           | `SERVICE_ADMINISTRATOR`                             | All     |
| `POST /v1/staff/characters/approve`                        | `MODERATOR_CHIEF` or `ADMINISTRATOR` or `DEVELOPER` | Any one |
| `POST /v1/staff/characters/reject`                         | `MODERATOR_CHIEF` or `ADMINISTRATOR` or `DEVELOPER` | Any one |
| `GET /v1/staff/characters/pending`                         | `MODERATOR_CHIEF` or `ADMINISTRATOR` or `DEVELOPER` | Any one |
| `PATCH /v1/users/{userId}/characters/{characterId}/wallet` | `ADMINISTRATOR`                                     | All     |
| `PUT /v1/users/{userId}/characters/{characterId}/wallet`   | `ADMINISTRATOR`                                     | All     |

<Note>
  **"Any one"** means the caller needs at least one of the listed flags set. **"All"** means the caller must hold that specific flag (though `SERVICE_ADMINISTRATOR` and `DEVELOPER` always pass regardless).
</Note>

***

## Permission Errors

When you call an endpoint without the required permissions, the API responds with either a `401 Unauthorized` or `403 Forbidden` status code and a JSON body describing the error.

**401 Unauthorized** — No valid session token was provided, or the token has expired:

```json theme={null}
{
  "error": "Unauthorized"
}
```

**403 Forbidden** — Your session is valid but you lack the required permission flags:

```json theme={null}
{
  "error": "Unauthorized"
}
```

<Warning>
  You cannot self-assign or escalate your own permissions. Roles are assigned exclusively by platform administrators through Discord role management, and are synced to your account when your Discord data is refreshed during login.
</Warning>

***

## Checking Permissions Programmatically

To check whether a `permissions` string includes a specific flag, perform a bitwise AND against the flag's bit value:

```typescript theme={null}
// TypeScript / JavaScript (using BigInt for 64-bit safety)
const permissions = BigInt("34"); // value from the API
const USER_FLAG = 1n << 1n;       // bit 1
const STAFF_FLAG = 1n << 5n;      // bit 5

const isUser  = (permissions & USER_FLAG)  !== 0n; // true
const isStaff = (permissions & STAFF_FLAG) !== 0n; // false
```

```python theme={null}
# Python
permissions = int("34")
USER_FLAG  = 1 << 1   # bit 1
STAFF_FLAG = 1 << 5   # bit 5

is_user  = bool(permissions & USER_FLAG)   # True
is_staff = bool(permissions & STAFF_FLAG)  # False
```