Authentication
Secure your API requests with workspace API keys
API Keys
The TagLogger API uses API keys for authentication. Every request must include a valid key—we use it to identify your workspace and check the key's scopes.
Keys are workspace-level credentials. If you suspect a key has been compromised, revoke it immediately from Settings → API Keys and create a replacement.
Key Types
Live Keys
Prefixed tl_live_. Use these in production. Live keys have access to your workspace within the scopes assigned to them.
Test Keys
Prefixed tl_test_. The prefix is a label only—a test key reads the same workspace data as a live key. There is no separate sandbox dataset in v1. Use test keys to keep development and production credentials distinct so you can revoke one without affecting the other.
Using Your Key
Send your API key on every request using either header:
# Bearer token (recommended) Authorization: Bearer tl_live_xxxxxxxxxxxxx # Or as a header X-API-Key: tl_live_xxxxxxxxxxxxx
Both methods are equivalent. Choose whichever fits your HTTP client better. Never expose your API key in client-side code or version control.
Scopes
Each API key has scopes that determine what it can access. Request the minimum scopes your integration needs.
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 their workspace branding.
manage:customer-pages
Create, update, revoke, rotate, and brand Customer Pages.
Key Management
You create and revoke keys yourself from Settings → API Keys. To rotate a key, create a replacement with the same scopes and revoke the old one. Creating your first key turns on API access for your workspace automatically. The raw key is shown to you only once at creation—copy it immediately and store it in a secrets manager.
When a key is revoked, it stops working immediately and any request that uses it fails with 401 unauthorized. Update your integration to a fresh key before retiring the old one.
Best Practices
- Never commit API keys to version control. Use environment variables or secrets managers.
- Use distinct keys for development and production so you can rotate one without disrupting the other.
- Request the minimum scopes each key needs. If an integration only reads tags, don't give it webhook permissions.
- Rotate keys periodically and immediately if you suspect compromise.
- Use separate keys for different services. This makes rotation and revocation simpler.
Errors
401 Unauthorized
{ "error": { "code": "unauthorized", "message": "Invalid API key." } }
403 Forbidden
{ "error": { "code": "forbidden", "message": "This API key is missing the required scope: read:locations" } }
403 Forbidden
{ "error": { "code": "api_disabled", "message": "The Developer API is not enabled for this workspace. Create an API key in your dashboard to enable it." } }A key can authenticate but still be rejected with 403 api_disabled if the workspace's API flag is off — creating a key from Settings → API Keys enables it. The same code is returned while the workspace has no active plan.
See Errors for the full list of error codes.
API Versioning
The API is versioned through the URL path. Every endpoint lives under the /v1 prefix—for example, https://api.taglogger.com/v1/tags. v1 is the current, stable version.
Expect backward-compatible additions to v1 over time: new endpoints, new optional request parameters, and new fields on existing responses. Write a tolerant client so these never break your integration:
- Ignore response fields you don't recognize.
- Don't depend on the ordering of keys within a JSON object.
- Treat resource identifiers as opaque strings. Don't parse them or assume a fixed length or prefix—the prefixes shown in examples are illustrative only.