Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Verifieddanny/BurnGuard/llms.txt

Use this file to discover all available pages before exploring further.

Sync tokens authenticate the proxy, not a user. When the local BurnGuard binary flushes usage records to the cloud every 60 seconds, it presents a sync token as proof that it belongs to your account. Without a valid token the proxy still runs and enforces budgets locally — it just cannot upload data to the dashboard.

​
What a Sync Token Looks Like

Every token is prefixed with bg_ followed by a lowercase hex string generated server-side: 
bg_82f72566bd4662be9a3f1dc7e...
The full token is only returned once — at creation — and is never retrievable again from the API or dashboard. The backend stores only a cryptographic hash of the token.

​
How the Proxy Uses the Token

The proxy reads the token from burnguard.yaml under sync.token and sends it as a Bearer credential when posting batched usage records to the cloud: 
POST /v1/usage
Authorization: Bearer bg_82f72566bd4662be...
Content-Type: application/json
The backend resolves the token to a user account, records the usage, and updates last_used_at on the token row.

​
Creating a Token

1

Open the Tokens page

Sign in at burnguard.run and click Tokens in the left sidebar.
2

Click 'Create token'

Click the Create token button in the top-right corner of the page. A modal will appear asking for a token name.
3

Name the token

Enter a descriptive name that identifies the proxy instance — for example production-proxy, dev-machine, or staging. Names are for your reference only and can be anything.
Token name: production-proxy
4

Copy the token immediately

After clicking Generate token, the full token string is displayed once inside the modal. Copy it before closing — it cannot be retrieved again.
bg_82f72566bd4662be9a3f1dc7e...
5

Add the token to burnguard.yaml

Paste the token under the sync block in your burnguard.yaml:
sync:
  enabled: true
  token: "bg_82f72566bd4662be9a3f1dc7e..."
  url: "https://api.burnguard.run"
  interval: 60
Restart the proxy with burnguard start to apply the change.
The raw token is shown exactly once — in the creation modal. Once you close it, neither the dashboard nor the API can return the plaintext value again. If you lose it, revoke the token and create a new one.
The API call the dashboard makes under the hood is: 
POST /v1/tokens
Authorization: Bearer <session_id>
Content-Type: application/json

{"name": "production-proxy"}
The response envelope contains a CreatedToken object: 
{
  "data": {
    "token": "bg_82f72566bd4662be9a3f1dc7e...",
    "message": "Save this token — it won't be shown again"
  }
}

​
Listing Tokens

GET /v1/tokens returns a SyncToken[] array of all tokens associated with your account. The Tokens page displays these as a table. Each SyncToken object has the following fields:
FieldTypeDescription
idnumberUnique token ID
user_idnumberID of the account that owns this token
namestringThe label you gave the token at creation
created_atstringWhen the token was generated (shown as relative time, e.g. “3 days ago”)
last_used_atstring | nullWhen the proxy last successfully synced using this token — — if it has never synced
last_used_at is the fastest way to confirm that a proxy is actively pushing data. If it has not updated in more than a few minutes and the proxy is running, check that the token in burnguard.yaml matches the one shown here.

​
Revoking a Token

Click the trash icon on the right side of any token row to revoke it. The UI sends DELETE /v1/tokens/{id}.
The DELETE /v1/tokens/{id} route is not yet mounted on the backend. The revoke button is present in the UI and the API client code is wired up, but the server-side handler and route are pending. Clicking the trash icon will result in an error until this endpoint is added. If you need to stop a token from syncing today, contact support or rotate the token by creating a new one and removing the old token value from burnguard.yaml.
After a token is successfully revoked:
  1. The proxy will log sync failures (it continues running and enforcing budgets locally).
  2. Generate a new token from the Tokens page.
  3. Update sync.token in burnguard.yaml with the new value.
  4. Restart burnguard start.
Name tokens by environment or machine — laptop, ci-runner, prod-server — so you can identify and revoke the right one immediately if a machine is decommissioned or a config file is accidentally exposed.

​
Multiple Tokens

You can create as many tokens as you need — one per proxy instance is the recommended pattern. All tokens report usage to the same dashboard account, so a single Overview page covers every environment at once. 
Tokens
├── laptop          last used 2 minutes ago
├── staging-server  last used 8 minutes ago
└── prod-server     last used 1 minute ago
Each token has an independent last_used_at timestamp, so you can see at a glance which environments are active and which are stale.

​
Token Security

Treat sync tokens the same way you treat API keys: keep them out of version control, do not log them, and do not share them across teams or environments. If a token is exposed, revoke it immediately from the Tokens page and generate a replacement.
Specific practices to follow:
  • Add burnguard.yaml to .gitignore if it contains a real token, or use an environment variable substitution and keep the YAML in version control with a placeholder.
  • In CI/CD pipelines, inject the token via a secret manager and write it to burnguard.yaml at startup rather than committing it.
  • Rotate tokens periodically in long-running environments as a matter of hygiene.

Build docs developers (and LLMs) love

Get started for freeTalk to us