Workspace token buckets and monthly caps

Open Tokens → Workspace tokens → Manage. You can also open a workspace settings sheet to review its current spending source and monthly cap, then choose Open token settings.

Choose one spending source

In Manage workspace tokens, select one of the two spending-source cards. The selected card is highlighted. If you are unsure which source fits your workspace, choose Help me decide beside the section heading to open this guide.

• Shared account balance: workspace actions that use tokens use only shared available tokens.
• Token bucket: workspace actions that use tokens use only tokens dedicated to that workspace.

There is no source fallback. This makes the administrator's budget choice predictable: a bucket-funded workspace cannot silently consume shared tokens.

When a workspace is active, the top bar shows its effective available tokens. The indicator uses the shared-balance icon or token-bucket icon to match that workspace's selected spending source.

The Workspace tokens table keeps an assigned bucket balance visible even when that workspace spends from the shared account balance. In that case, use the information icon beside the bucket balance to see why those bucket tokens are inactive and how the workspace's effective availability is derived from the shared balance and any monthly cap.

The table highlights zero effective availability in red for workspaces using the shared account balance. For a bucket-funded workspace with an empty bucket, both the bucket balance and effective availability are highlighted in red so the bucket can be replenished quickly.

Use Add tokens to stage existing shared token lots for the workspace. The label shows the shared tokens currently available for another staged addition, and the input uses that amount as its maximum. If an entered amount exceeds the shared availability, the dialog explains the limit instead of leaving the disabled action unexplained. Enter a smaller amount under Return tokens to stage available, unheld tokens for return to the shared balance, or use Return all to stage the complete unused bucket balance. These controls do not move tokens immediately. The dialog always shows the current bucket balance and held tokens. After you stage an addition or return, a preview appears below the return controls with the pending change, bucket balance after saving, shared available balance after saving, and effective workspace availability after saving. The preview stays hidden when the bucket balance is unchanged.

If the selected spending source is Shared account balance while the bucket still contains tokens, the dialog explains that those bucket tokens are not being used. They remain reserved for that workspace until its spending source changes to Token bucket, or until an administrator returns them to the shared balance.

Choose Save settings to apply the bucket adjustment, spending source, and monthly cap together. Closing or cancelling the dialog discards the draft. Partial returns may use the available balance while other tokens are held. Returning all tokens or switching from bucket to shared shows the exact return amount and requires confirmation, and active bucket-funded holds must settle first. If the bucket balance changes while the dialog is open, LeadsParrot refreshes it and asks you to review the latest values before saving again.

Email notifications for bucket additions and returns include the pending token change, the workspace bucket balance before and after, the shared available balance before and after, and effective workspace availability after saving. A separate monthly-cap notification is sent only when the cap changes between unlimited and limited or when its limited amount changes; saving a bucket-only adjustment does not repeat the current cap setting.

The confirmation highlights balance-emptying changes. Moving every shared available token into a workspace bucket warns that account-level actions requiring tokens will be blocked until shared tokens are replenished. Emptying a bucket that remains the workspace's spending source warns that workspace actions requiring tokens will be blocked until the bucket is replenished or the spending source changes. When the workspace is switching to shared spending, the confirmation explains that the emptied bucket is being replaced by the shared account balance instead of showing an incorrect blocked-action warning.

Archiving a workspace also previews the return and returns every unused bucket token. Active bucket holds block archival.

Monthly caps are separate

A cap limits actual monthly workspace spending regardless of its source. It resets at the first instant of each UTC calendar month; bucket balances do not reset. LeadsParrot warns token-access users once at 80% and once when the cap is reached.

In Manage workspace tokens, the monthly cap amount and No monthly workspace cap option share one responsive control. Select No monthly workspace cap to disable the amount field and leave workspace spending unlimited by a monthly cap. Clear that option to enter a token amount; the selected spending source can still run out of tokens before the cap is reached.

Lowering a cap below tokens already spent plus held requires confirmation. Queued affected processes are cancelled; running processes receive a cooperative stop request and stop at the next safe checkpoint. Unused holds are released, and the initiator receives a web app notification.

Effective availability examples

• Bucket 200, cap remainder 100: effective availability is 100.
• Bucket 50, cap remainder 100: effective availability is 50.
• Shared available 800, cap remainder 40: effective availability is 40.
• Empty bucket, unlimited cap: effective availability is zero; shared tokens are not used.