# How to Become Admin in QBCore

QBCore admin permissions are **ACE/principal permissions**, not a column in the `players` table.
Do not add or edit a fictional `players.permission` field.

The default QBCore permission names are:

- `god`
- `admin`
- `mod`

They are configured in `QBCore.Config.Server.Permissions` and backed by FiveM ACE rules.

![QBCore ACE permission and staff principal flow](/diagrams/permissions.svg)

*Conceptual diagram; verify the behavior against your installed resource version.*

## Recommended setup: persistent permissions in server.cfg

Use `server.cfg` for persistent staff access.

```cfg
## Permissions ##

add_ace group.admin command allow

{{addPrincipalsMaster}}

# Allow qb-core to create and manage command ACEs
add_ace resource.qb-core command allow

# God can run all commands
add_ace qbcore.god command allow

# Inheritance
add_principal qbcore.god group.admin
add_principal qbcore.god qbcore.admin
add_principal qbcore.admin qbcore.mod

# Staff
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx qbcore.god
add_principal identifier.license:yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy qbcore.admin
```

The txAdmin recipe uses `{{addPrincipalsMaster}}` to grant the server owner its generated principal.
Keep that line when your recipe includes it.

### Find the player's license

The framework uses the Rockstar/FiveM license identifier for persistent principals.

A practical way to retrieve it:

1. Open the player in the txAdmin web panel.
2. Inspect the player's identifiers.
3. Copy the value beginning with `license:`.
4. Add it to `server.cfg` as an `identifier.license:...` principal.
5. Restart the server or execute the relevant ACE command from the server console.

Example:

```cfg
add_principal identifier.license:0123456789abcdef0123456789abcdef01234567 qbcore.admin
```

## Grant permissions in game

Current `qb-core` registers:

```text
/addpermission [id] [permission]
/removepermission [id] [permission]
```

Examples:

```text
/addpermission 12 admin
/addpermission 8 god
/removepermission 12 admin
```

These commands are restricted to `god`.

Internally they call `QBCore.Functions.AddPermission` and
`QBCore.Functions.RemovePermission`, which add or remove a runtime principal for the connected
player and refresh that player's command suggestions.

> **Runtime grants are not your persistent staff list**
> Use `server.cfg` for permissions that must survive reconnects and restarts. Treat
> `/addpermission` as a runtime administration tool.

## Use qb-adminmenu

The official administration resource is `qb-adminmenu`.

With the resource installed and your permission configured:

1. Run `/admin`.
2. Open **Player Management**.
3. Select the target player.
4. Open **Permissions**.
5. Choose the intended group.

See [qb-adminmenu](/docs/resources/qb-adminmenu) for the resource-specific interface and
[Admin Commands](/docs/guides/admin-commands) for command ownership.

## How the permission hierarchy works

The common recipe creates this chain:

```text
qbcore.god
├─ group.admin
└─ qbcore.admin
   └─ qbcore.mod
```

That means a `god` principal inherits the admin and mod layers, while an `admin` principal inherits
the mod layer.

The core also creates command-specific ACEs for custom QBCore command permissions.

## Add a custom permission group

The current core defines its known groups in `config.lua`:

```lua
QBCore.Config.Server.Permissions = { 'god', 'admin', 'mod' }
```

To add a custom group, extend the table:

```lua
QBCore.Config.Server.Permissions = { 'god', 'admin', 'mod', 'leo' }
```

Then grant it through ACE:

```cfg
add_principal identifier.license:0123456789abcdef0123456789abcdef01234567 qbcore.leo
```

### Restrict a QBCore command to that group

```lua
QBCore.Commands.Add('spikes', 'Place spike strips', {}, false, function(source)
    -- Server-authoritative spike strip logic
end, 'leo')
```

For permission names other than the built-in ignore-list entries, `QBCore.Commands.Add`
automatically creates a command ACE equivalent to:

```cfg
add_ace qbcore.leo command.spikes allow
```

That lets FiveM enforce the command restriction before the callback runs.

You can also grant or remove a principal dynamically from trusted server code when a role changes,
but persistent identity-based staff access belongs in `server.cfg`.

## Verify the setup

### Check the core config

Confirm the intended group exists in:

```text
qb-core/config.lua
```

The current default is:

```lua
QBCore.Config.Server.Permissions = { 'god', 'admin', 'mod' }
```

### Check server.cfg

Confirm these pieces exist:

- `add_ace resource.qb-core command allow`
- `add_ace qbcore.god command allow`
- the expected inheritance rules
- your exact `identifier.license:...` principal

### Check in game

After reconnecting, test a command that is actually owned by `qb-core` or `qb-adminmenu`.
Do not use a random third-party command as your permission test.

Useful checks:

```text
/admin
/addpermission
```

Whether a specific command exists depends on the resources currently installed.

## Troubleshooting

### `/admin` does not exist

Check that `qb-adminmenu` is installed and started after `qb-core`.

```cfg
ensure qb-core
ensure qb-adminmenu
```

The admin menu is not built into the core resource itself.

### `/addpermission` says you do not have permission

The command is registered with the `god` permission. Verify your persistent principal first:

```cfg
add_principal identifier.license:YOUR_LICENSE qbcore.god
```

Then reconnect after the ACE configuration is loaded.

### A principal works until restart, then disappears

You granted it at runtime. Put persistent staff principals in `server.cfg`.

### You edited the database but nothing changed

That is expected if you added or edited a `permission` column. Current QBCore permissions are ACE
based. The framework's normal `players` schema does not use a `permission` field for staff access.

See [Database schema](/docs/database/core-schema).

### A custom permission command is visible to everyone

Check all three layers:

1. The custom name exists in `QBCore.Config.Server.Permissions`.
2. The command was registered with that permission as the final argument.
3. The target player has the corresponding `qbcore.<permission>` principal.

Also keep:

```cfg
add_ace resource.qb-core command allow
```

so the core can create command ACEs.

## Security notes

- Grant `god` only where full command access is intended.
- Prefer the least-powerful permission that satisfies the staff role.
- Keep persistent principals in version-controlled or otherwise audited server configuration.
- Do not authorize privileged gameplay actions from client-supplied role or permission data.
- When adding custom commands, validate target IDs, arguments, server-side state and ownership inside
  the command callback as well.

## Related documentation

- [QBCore Commands API](/docs/api/commands)
- [Admin Commands](/docs/guides/admin-commands)
- [qb-adminmenu](/docs/resources/qb-adminmenu)
- [Annotated server.cfg reference](/docs/installation/server-config)
- [Database schema](/docs/database/core-schema)

## Sources

- [Official QBCore permission guide](https://github.com/qbcore-framework/qb-docs/blob/main/guides/setting-permissions.md)
- [qb-core config.lua](https://github.com/qbcore-fivem/qb-core/blob/main/config.lua)
- [qb-core server commands](https://github.com/qbcore-fivem/qb-core/blob/main/server/commands.lua)
- [qb-core permission functions](https://github.com/qbcore-fivem/qb-core/blob/main/server/functions.lua)
- [QBCore txAdmin recipe server.cfg](https://github.com/qbcore-fivem/txAdminRecipe/blob/main/server.cfg)

Last verified against current upstream files: **2026-09-27**.
