Authentication & API keys
Give each integration the access it needs, with a separate key you can rotate or revoke.
Create a server API key
Only the workspace owner can manage keys. Open Settings / API access, choose Create key, enter a useful name and select permissions. Choose an expiry or Never expires, then confirm the action. Copy the token before closing the dialog.
If two-factor authentication is enabled, enter a fresh six-digit authenticator code. Otherwise, enter your current password; the page also shows a reminder to enable 2FA. Creation, rotation and revocation all require this confirmation.
Keys use tcr_<public-key-id>.<secret>. TruCom stores a hash rather than a retrievable token. Each key belongs to its workspace. A widget is selected only when you grant widget:identify; customer, ticket, feature-request and conversation access work independently of widget display settings.
Send the key as a Bearer token
Keep the key in your server environment or secret manager. Send it in the Authorization header. Do not place it in browser JavaScript, mobile app bundles, URLs or analytics events. The JavaScript widget needs a public widget key, never this secret.
curl "https://trucom.app/api/v1/rest/me" \
-H "Authorization: Bearer $TRUCOM_API_KEY" \
-H "Accept: application/json"Choose permissions
| Scope | Allows |
|---|---|
| customers:read | List, retrieve and look up customer profiles, including website attribute snapshots. |
| customers:write | Create, upsert and update customer profiles. Does not automatically grant read scope. |
| conversations:read | Read conversation summaries and public messages. |
| widget:identify | Issue signed identity tokens for this key’s widget. |
| tickets:read | List and retrieve tickets and their public replies. |
| tickets:write | Create tickets and submit customer replies. |
| feature_requests:read | Read feature requests, customer submissions and boards. |
| feature_requests:write | Create feature requests for a customer. |
Rotate or revoke a key
Rotate replaces the secret immediately, preserves permissions and expiry, and clears replay records. Confirm with your current password or a fresh authenticator code, then save the replacement key and update your integration.
Revoke stops requests using that key. Revoked or expired keys cannot be reactivated. Revocation needs the same security confirmation. Keys also stop working if their issuer loses owner access or the workspace is deleted.
Choose Never expires for a key with no scheduled expiry, or choose a timed expiry of up to 365 days. GET /me returns expires_at as null for non-expiring keys. You can rotate or revoke a non-expiring key at any time.
Plan for request limits
The default limit is 120 requests per minute per key. Successful responses include X-RateLimit-Limit and X-RateLimit-Remaining. A 429 response includes Retry-After in seconds; wait at least that long, with jitter, before retrying. Invalid credentials return 401.