# qb-vehiclekeys: keys, locks and exports

`qb-vehiclekeys` tracks access to vehicle plates, lock/unlock actions, key sharing, carjacking and hotwiring. For integrations, use its **server exports**, not internal network events. This reference is pinned to [commit 36b54c2](https://github.com/qbcore-fivem/qb-vehiclekeys/tree/36b54c2dc20f591eb613be22d892e982bf87fbbf).

## Installation and dependencies

1. Start `qb-core` first. The resource's server code also uses `qb-inventory` for lockpick removal.
2. Start `qb-vehiclekeys` with its `NUI` assets, locales, client/server scripts and `config.lua`.
3. Ensure vehicle shop, garage and custom spawn scripts follow the same plate format and assign keys through the server.
4. Test spawned, owned, job and borrowed vehicles, plus reconnect and resource restart.

## Official server exports

These functions are exported in [`server.lua`](https://github.com/qbcore-fivem/qb-vehiclekeys/blob/36b54c2dc20f591eb613be22d892e982bf87fbbf/server.lua).

| Export | Signature | Behavior |
| --- | --- | --- |
| `GiveKeys` | `GiveKeys(playerSource, plate)` | Grants key access; if plate omitted, tries the player's current vehicle |
| `RemoveKeys` | `RemoveKeys(playerSource, plate)` | Revokes key access for the plate |
| `HasKeys` | `HasKeys(playerSource, plate)` | Returns boolean for a player's plate access |

~~~lua filename="server.lua"
-- In a trusted server-side vehicle-delivery handler:
local playerSource = source
local plate = 'DEMO123' -- Use your server-created vehicle's real plate

if not exports['qb-vehiclekeys']:HasKeys(playerSource, plate) then
    exports['qb-vehiclekeys']:GiveKeys(playerSource, plate)
end

-- When server-owned rules require revoking the same access:
-- exports['qb-vehiclekeys']:RemoveKeys(playerSource, plate)
~~~

**Do not** let an arbitrary client select the player ID or plate to grant. The handler responsible for a purchase, spawn or job vehicle must establish the vehicle and player's entitlement server-side. The example is an integration fragment, **not** an event handler accepting user input.

### Client helpers

[`client.lua`](https://github.com/qbcore-fivem/qb-vehiclekeys/blob/36b54c2dc20f591eb613be22d892e982bf87fbbf/client.lua) also exports `HasKeys` for the local client and `addNoLockVehicles` / `removeNoLockVehicles` for local no-lock vehicle lists. Use the server version for authorization-sensitive decisions.

## Real configuration options

| Option | Purpose |
| --- | --- |
| `Config.PersistentKeys` | Enables restoring saved keys from player metadata on reconnect |
| `Config.SharedKeys` | Job-related key sharing rules |
| `Config.UseKeyfob` | Keyfob lock UI behavior |
| `Config.LockToggleDist` | Lock interaction distance |
| `Config.LockNPCDrivingCars` / `Config.LockNPCParkedCars` | NPC vehicle locking |
| `Config.CarJackEnable` | Enables/disables carjacking behavior |
| `Config.CarjackChance` / `Config.HotwireChance` | Chance-based gameplay |
| `Config.AlertCooldown` | Police alert cooldown |
| `Config.ImmuneVehicles` / `Config.NoLockVehicles` | Vehicle exceptions |

With `PersistentKeys` enabled, `GiveKeys` updates `PlayerData.metadata.vehicleKeys`, and `HasKeys` consults that metadata when needed. Changing the setting does **not** by itself migrate key data to a custom garage schema.

## Events and commands

The reviewed source registers these **internal** server events: `qb-vehiclekeys:server:GiveVehicleKeys`, `AcquireVehicleKeys`, `RemoveVehicleKeys`, `breakLockpick` and `setVehLockState` (all with the `qb-vehiclekeys:server:` prefix). The acquisition event expects a vehicle network ID and checks proximity, but a proximity check alone does not establish ownership. Custom scripts should use the trusted server exports instead.

Available commands in this revision:

- `/givekeys` — initiates key sharing through the client flow.
- `/addkeys` — admin command to grant keys by player/plate.
- `/removekeys` — admin command to remove keys by player/plate.
- Client commands `/togglelocks` and `/engine` control local lock/engine actions.

Never grant keys through a client-controlled net event simply because a vehicle is nearby.

## Why do my car keys disappear?

| Symptom | First check |
| --- | --- |
| Keys missing after reconnect | `Config.PersistentKeys` and saved `vehicleKeys` metadata |
| Keys work for another vehicle | Plate normalization: trim whitespace consistently in garage, shop and key resources |
| Car spawns without keys | Did the trusted server spawn/delivery flow call `GiveKeys` with the actual plate? |
| Job vehicle access is wrong | `Config.SharedKeys` and the player's active job/grade |
| No keys after upgrading | Compare old and new persistent-key model; test metadata and live-session cache separately |
| `No such export GiveKeys` | Ensure caller is on the **server**, resource started and correct revision deployed |

## Update checklist

1. Pin current `qb-vehiclekeys`, `qb-core`, `qb-inventory` and garage/vehicle-shop revisions.
2. Test server `GiveKeys`, `RemoveKeys` and `HasKeys` (including invalid player IDs).
3. Verify access after logout and after resource restart with persistent keys on and off.
4. Audit all scripts using `AcquireVehicleKeys` or `setVehLockState` and move privileged operations to server-authorized exports.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-vehiclekeys/tree/36b54c2dc20f591eb613be22d892e982bf87fbbf) · [Server exports and events](https://github.com/qbcore-fivem/qb-vehiclekeys/blob/36b54c2dc20f591eb613be22d892e982bf87fbbf/server.lua) · [Client helpers](https://github.com/qbcore-fivem/qb-vehiclekeys/blob/36b54c2dc20f591eb613be22d892e982bf87fbbf/client.lua) · [Configuration](https://github.com/qbcore-fivem/qb-vehiclekeys/blob/36b54c2dc20f591eb613be22d892e982bf87fbbf/config.lua)

For garage/vehicle persistence see [vehicle-state troubleshooting](/docs/troubleshooting/vehicle-state).
