API Keys
How API keys, scopes, and limits work in your workspace
Overview
API keys are the credentials your integrations use to authenticate with the TagLogger API. Each key belongs to a workspace and is configured with specific scopes to limit what it can access.
See the Authentication page for how to send keys in requests.
Getting a Key
You create and manage keys yourself from Settings → API Keys in your dashboard. Click Create API key, choose the scopes your integration needs, and copy the key. Creating your first key turns on API access for your workspace automatically.
Copy your key when it is created. The raw key is shown only once and cannot be recovered—if you lose it, revoke it and create a new one.
Key Format
API keys follow a consistent format so you can identify them at a glance:
tl_live_— Production keys. Use these for live workflows.tl_test_— Test keys. The prefix is a label only; a test key reads the same workspace data as a live key (there is no separate sandbox in v1).
The rest of each key is a random identifier. Treat the whole string as a secret.
Key Scopes
Each key carries only the scopes your integration needs. This principle of least privilege limits the damage if a key is compromised.
read:tags
List and read tag metadata (name, hardware ID, status, and last-seen time). Exact coordinates require read:locations.
manage:tags
Activate or deactivate tags and pause or resume alerts and new location recording.
read:locations
Read current location, location history, and fleet delta snapshots.
read:geofences
List and read geofence configuration (center, radius, target tags).
manage:geofences
Create, update, and delete geofences within the key's tag scope. All-tags geofences require an all-tags key. Setting or clearing email recipient lists also requires read:locations.
manage:webhooks
Create, list, update, delete, and rotate webhook subscriptions, and send test deliveries. Subscriptions deliver events for every tag in the workspace, so creating, updating, deleting, or rotating one requires an all-tags key; subscribing to tag.moved or geofence.* events (payloads carry coordinates) also requires read:locations.
read:share-links
List and read public tag share links, including their status and access counts.
manage:share-links
Mint and revoke public, expiring tag share links.
read:customer-pages
List and read multi-tag Customer Pages and branding.
manage:customer-pages
Create, update, revoke, rotate, and brand Customer Pages.
Limits
- A workspace can have up to 25 active API keys. Revoke an unused key before creating another once you reach the limit.
- Each request is rate limited per key. See Usage & Rate Limits for the current limits and headers.
Rotating or Revoking a Key
Rotate or revoke keys yourself from Settings → API Keys — for a periodic refresh or after a suspected compromise. A clean rotation looks like:
- Create a new key with the same scopes as the old one.
- Update your application or service to use the new key.
- Verify the new key is working correctly.
- Revoke the old key.
Once a key is revoked it stops working immediately—any request using it fails with 401 unauthorized, and a revoked key cannot be restored.
Best Practices
- Never share keys. Use a dedicated key per service or environment.
- Use environment variables. Store keys in a secrets manager, never in code or config files.
- Separate environments. Keep development and production keys distinct so rotating one doesn't affect the other.
- Rotate periodically. Consider rotating keys every 90 days for high-security applications.
- Assign minimum scopes. If a key only needs to read tags, don't grant webhook management.