Permission Roles and Access Control in CA Colombia

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.

{
  "userId": "1234567890123456789",
  "permissions": "34",
  "...": "..."
}

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.

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.

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.

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

“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).

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:

{
  "error": "Unauthorized"
}

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

{
  "error": "Unauthorized"
}

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.

Checking Permissions Programmatically

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

// 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
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

Get Started

Core Concepts

Guides

Reference

Permission Roles and Access Control in CA Colombia

How Bitfield Permissions Work

Permission Roles

Rate Limit Bypass

Endpoint Permission Requirements

Permission Errors

Checking Permissions Programmatically

​How Bitfield Permissions Work

​Permission Roles

​Rate Limit Bypass

​Endpoint Permission Requirements

​Permission Errors

​Checking Permissions Programmatically

How Bitfield Permissions Work

Permission Roles

Rate Limit Bypass

Endpoint Permission Requirements

Permission Errors

Checking Permissions Programmatically