# FiveManage Setup (/docs/orbit-studios-resources/orbit-dynamichud/fivemanage)



# FiveManage API key setup [#fivemanage-api-key-setup]

FiveManage is required only when `Config.ControlPanel.settingsShare.thumbnails` is enabled. DynamicHUD uses it to store player-approved Settings Share screenshots. Presets continue to work with generated fallback previews when thumbnails are disabled.

<Callout type="warn" title="Keep the key server-side">
  Never put the API key in `shared/config.lua`, client Lua, NUI code, frontend environment variables, screenshots, or a source repository. DynamicHUD reads it from a server convar and never sends it to a player.
</Callout>

## Create the API key [#create-the-api-key]

1. [Create a FiveManage account](https://www.fivemanage.com/) or sign in to an existing account.
2. Create or select the team that should own the uploaded HUD thumbnails.
3. Open the [FiveManage dashboard](https://app.fivemanage.com/) and navigate to **Tokens**.
4. Select **Create token** and give it a recognizable name such as `Orbit Dynamic HUD 2.0 thumbnails`.
5. Choose the **Images** scope for least privilege. A **Media** token also works, but grants image, video, and audio access that this integration does not need.
6. Copy the generated token and store it as a protected server secret.

FiveManage documents the same account, team, and token flow in its [upload API first steps](https://docs.fivemanage.com/guides/uploading-files/first-steps). API keys are managed from the dashboard Tokens page.

## Configure DynamicHUD [#configure-dynamichud]

Put the token in `server.cfg` before `orbit-dynamichud-v2` starts:

```properties title="server.cfg"
set orbit_fivemanage_api_key "YOUR_FIVEMANAGE_API_KEY"
```

Keep the server configuration pointed at that convar:

```lua title="resources/[orbit]/orbit-dynamichud-v2/server/config.lua"
Config.SettingsShareServer.thumbnail = {
    captureProvider = 'screencapture', -- or 'screenshot-basic'
    apiKey = GetConvar('orbit_fivemanage_api_key', ''),
    presignedUrlEndpoint = 'https://api.fivemanage.com/api/v3/file/presigned-url',
    fileEndpoint = 'https://api.fivemanage.com/api/v3/file',
    deleteUnusedThumbnails = true
}
```

Enable thumbnails in the shared feature configuration:

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/config.lua"
Config.ControlPanel.settingsShare.thumbnails = true
```

Start exactly the capture provider selected in `captureProvider`, and start it before DynamicHUD:

```properties title="server.cfg"
# Choose one provider, matching server/config.lua.
ensure screencapture
# ensure screenshot-basic

ensure orbit-dynamichud-v2
```

You do not need to install the FiveManage SDK resource for this integration. DynamicHUD requests FiveManage v3 presigned upload URLs through its own server module.

## How the key stays private [#how-the-key-stays-private]

1. The server validates the player, feature state, preset limits, cooldown, and upload request.
2. The server authenticates with FiveManage and requests a short-lived presigned URL.
3. The client captures the composed game and HUD frame and uploads only to that temporary URL.
4. The server validates the returned HTTPS host, storage marker, file path, and image bytes before saving the thumbnail.
5. When configured, the server deletes the managed file after its preset is deleted or receives a replacement thumbnail.

This follows FiveManage's recommended [presigned URL flow](https://docs.fivemanage.com/guides/uploading-files/presigned-urls): the permanent token stays on the server while the client receives temporary upload permission.

## Verify the setup [#verify-the-setup]

1. Temporarily set `Config.Debug = true`.
2. Restart `orbit-dynamichud-v2` rather than refreshing only the NUI.
3. Check the server console startup line for the selected provider, a started provider resource, and `apiKey=present`.
4. Open Settings Share, begin an upload, and capture a thumbnail.
5. Save privately or submit the preset. The staged image is uploaded only when that preset action is confirmed.
6. Confirm the thumbnail appears in the preset and in the FiveManage storage dashboard.
7. Return `Config.Debug` to its production value after verification.

## Troubleshooting [#troubleshooting]

| Symptom                               | Check                                                                                                                                                |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key reported missing              | The `set orbit_fivemanage_api_key` line must appear before `ensure orbit-dynamichud-v2`; restart the resource after changing it.                     |
| Capture provider unavailable          | The configured `screenshot-basic` or `screencapture` resource must be installed and started first. Names must match exactly.                         |
| FiveManage returns `401`              | Regenerate or rotate the token and confirm it belongs to the intended team with Images or Media access.                                              |
| Upload returns a disallowed host      | Keep the default FiveManage CDN hosts, or explicitly add a trusted custom CDN hostname to `thumbnail.allowedHosts`. Never allow arbitrary hosts.     |
| Capture succeeds but publishing fails | Check the server console for presigned URL, upload verification, cooldown, or database errors; check the client F8 console for capture-stage errors. |
| Repeated network timeouts             | Keep retries bounded and review `uploadAttempts`, `retryDelayMs`, and `timeoutMs` rather than creating an unbounded retry loop.                      |

Rotate the token immediately if it is exposed. Update the convar, restart DynamicHUD, and revoke the old token in the FiveManage dashboard.