API Documentation

Complete API reference for LuaBeans - Community Manager FiveM integration.

Overview

LuaBeans - Community Manager provides a REST API for FiveM resources to access department information, duty state, and user data. The API uses Bearer token authentication and returns JSON data.

Base URL

All API endpoints are prefixed with:

https://your-domain.com/api/leo

Authentication

All API requests must include a Bearer token in the Authorization header:

Authorization: Bearer YOUR_LEO_API_TOKEN

The token must match the LEO_API_TOKEN value in your web panel's .env file.

Endpoints

GET /api/leo/user/:discordId/departments

Fetches a player's departments and ranks.

URL: /api/leo/user/:discordId/departments

Method: GET

Authentication: Required (Bearer token)

URL Parameters:

• discordId (required) - Player's Discord ID

Headers:

Authorization: Bearer YOUR_LEO_API_TOKEN

Response (Success - 200):

{
  "ok": true,
  "departments": [
    {
      "id": 1,
      "name": "Police Department",
      "slug": "police",
      "rankId": 5,
      "rankName": "Officer",
      "rankOrder": 3,
      "permissions": [
        "leo.duty",
        "leo.vehicle",
        "leo.uniform"
      ]
    },
    {
      "id": 2,
      "name": "Sheriff's Office",
      "slug": "sheriff",
      "rankId": 8,
      "rankName": "Deputy",
      "rankOrder": 2,
      "permissions": [
        "leo.duty"
      ]
    }
  ]
}

Response (Error - 401):

{
  "ok": false,
  "error": "Unauthorized"
}

Response (Error - 404):

{
  "ok": false,
  "error": "User not found"
}

Response (Error - 500):

{
  "ok": false,
  "error": "Internal server error"
}

Example (Lua):

local discordId = "123456789012345678"
local url = GetConvar('LUABEANS_API_BASE', 'https://hub.example.com') .. '/api/leo/user/' .. discordId .. '/departments'
local token = GetConvar('LUABEANS_LEO_API_TOKEN', '')

PerformHttpRequest(url, function(statusCode, response, headers)
  if statusCode == 200 then
    local data = json.decode(response)
    if data.ok then
      print("Departments:", json.encode(data.departments))
    end
  end
end, 'GET', '', {
  ['Authorization'] = 'Bearer ' .. token,
  ['Content-Type'] = 'application/json'
})

---

POST /api/leo/duty/:action

Updates a player's duty state.

URL: /api/leo/duty/:action

Method: POST

Authentication: Required (Bearer token)

URL Parameters:

• action (required) - on or off

Headers:

Authorization: Bearer YOUR_LEO_API_TOKEN
Content-Type: application/json

Body (for on action):

{
  "departmentId": 1,
  "discordId": "123456789012345678"
}

Body (for off action):

{
  "discordId": "123456789012345678"
}

Response (Success - 200):

{
  "ok": true,
  "message": "Duty state updated"
}

Response (Error - 400):

{
  "ok": false,
  "error": "Invalid request"
}

Response (Error - 401):

{
  "ok": false,
  "error": "Unauthorized"
}

Example (Lua - On Duty):

local discordId = "123456789012345678"
local departmentId = 1
local url = GetConvar('LUABEANS_API_BASE', 'https://hub.example.com') .. '/api/leo/duty/on'
local token = GetConvar('LUABEANS_LEO_API_TOKEN', '')

local body = json.encode({
  departmentId = departmentId,
  discordId = discordId
})

PerformHttpRequest(url, function(statusCode, response, headers)
  if statusCode == 200 then
    local data = json.decode(response)
    if data.ok then
      print("Player went on duty")
    end
  end
end, 'POST', body, {
  ['Authorization'] = 'Bearer ' .. token,
  ['Content-Type'] = 'application/json'
})

Example (Lua - Off Duty):

local discordId = "123456789012345678"
local url = GetConvar('LUABEANS_API_BASE', 'https://hub.example.com') .. '/api/leo/duty/off'
local token = GetConvar('LUABEANS_LEO_API_TOKEN', '')

local body = json.encode({
  discordId = discordId
})

PerformHttpRequest(url, function(statusCode, response, headers)
  if statusCode == 200 then
    local data = json.decode(response)
    if data.ok then
      print("Player went off duty")
    end
  end
end, 'POST', body, {
  ['Authorization'] = 'Bearer ' .. token,
  ['Content-Type'] = 'application/json'
})

Response Format

Success Response

All successful responses follow this format:

{
  "ok": true,
  "data": { ... }
}

Error Response

All error responses follow this format:

{
  "ok": false,
  "error": "Error message"
}

Error Codes

Status Code	Meaning	Description
200	OK	Request successful
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication token
404	Not Found	Resource not found (user, department, etc.)
500	Internal Server Error	Server error

Rate Limiting

API requests are rate-limited to prevent abuse:

• Default limit: 200 requests per minute per IP

• Rate limit headers: Standard rate limit headers included

• Rate limit exceeded: Returns 429 Too Many Requests

Best Practices

1. Cache Responses - Cache department data locally (LuaBeans Bridge caches for 5 minutes)

2. Handle Errors - Always check ok field in responses

3. Use HTTPS - Always use HTTPS in production

4. Secure Token - Never expose API token in client-side code

5. Validate Input - Validate Discord IDs and department IDs before requests

Integration Examples

Using with ESX

-- Get player's departments
function GetPlayerDepartments(source)
  local discordId = GetPlayerDiscordId(source)
  if not discordId then return {} end
  
  local url = GetConvar('LUABEANS_API_BASE', '') .. '/api/leo/user/' .. discordId .. '/departments'
  local token = GetConvar('LUABEANS_LEO_API_TOKEN', '')
  
  local departments = {}
  PerformHttpRequest(url, function(statusCode, response, headers)
    if statusCode == 200 then
      local data = json.decode(response)
      if data.ok and data.departments then
        departments = data.departments
      end
    end
  end, 'GET', '', {
    ['Authorization'] = 'Bearer ' .. token
  })
  
  -- Note: This is a simplified example - actual implementation should use callbacks
  return departments
end

Using with Custom Resources

-- Check if player has specific permission
function PlayerHasPermission(source, permission)
  local departments = GetPlayerDepartments(source)
  for _, dept in ipairs(departments) do
    if dept.permissions and #dept.permissions > 0 then
      for _, perm in ipairs(dept.permissions) do
        if perm == permission then
          return true
        end
      end
    end
  end
  return false
end

Troubleshooting

Authentication Errors

Error: 401 Unauthorized

Solutions:

1. Verify LEO_API_TOKEN matches in both FiveM config and web panel .env

2. Check token is sent in Authorization header

3. Verify token hasn't expired or been changed

4. Check token format: Bearer YOUR_TOKEN

User Not Found

Error: 404 Not Found

Solutions:

1. Verify player has Discord identifier: discord:123456789012345678

2. Check Discord ID is correct format (18-19 digits)

3. Verify user exists in database (try logging into web panel)

4. Sync user data: /syncme command in Discord or "Refresh roles" in web panel

Connection Errors

Error: Cannot connect to API

Solutions:

1. Verify LUABEANS_API_BASE is correct and accessible

2. Check web panel is running

3. Verify firewall allows connection from FiveM server

4. Check SSL certificate is valid (if using HTTPS)

5. Test API endpoint manually with curl

Rate Limiting

Error: 429 Too Many Requests

Solutions:

1. Implement caching (LuaBeans Bridge does this automatically)

2. Reduce request frequency

3. Use cached data instead of frequent API calls

4. Wait for rate limit to reset (usually 1 minute)

Related Documentation

• LuaBeans Bridge - FiveM integration resource

• LuaBeans Duty - Duty system UI

• FiveM Configuration - Complete FiveM setup