Skip to main content

​
API Keys & Access

Best practices:
  • Store API keys only on your backend (server-side).
  • Use secure secret management (e.g. environment variables, secret managers).
  • Never embed keys in:
    • Front-end JavaScript.
    • Mobile/desktop apps distributed to end-users.
    • Public repositories or logs.
For each workspace or integration:
  • Prefer a dedicated workspace-scoped API key instead of sharing one key across many systems.
It is recommended to:
  • Use separate API keys for:
    • Development.
    • Staging.
    • Production.
This allows you to:
  • Isolate data and actions per environment.
  • Rotate keys independently as needed.

​
Authentication & Authorization Behavior

A 401 Unauthorized typically means:
  • The Authorization header is missing.
  • The token or API key is not valid.
  • The token is not accepted for the requested endpoint.
Check:
  • Token format (e.g. Authorization: Bearer <token>).
  • That the key corresponds to the intended workspace and environment.
A 403 Forbidden indicates:
  • You are authenticated, but not allowed to perform this action or access this resource.
Common cases:
  • Attempting to access resources not belonging to the workspace associated with your token.
  • Using a token with insufficient privileges (where granular roles are configured).

​
Billing, Read-Only Mode & Quotas

When a workspace enters read-only mode (e.g. due to billing issues), write operations may fail with:
{
  "error": "READ_ONLY",
  "code": "READ_ONLY",
  "reason": "past_due"
}
Effects:
  • You may still be able to read data (e.g. leads, messages, lines).
  • Writes such as creating new messages or leads will be blocked.
Integration guidance:
  • Treat this as a hard stop for writes.
  • Surface clear messaging in your own UI or logs:
    • “Tuco workspace is in read-only mode; please resolve billing in Tuco.”
  • Avoid infinite retries; they will continue to fail until resolved.
At a high level:
  • Plan limits:
    • Define global ceilings (e.g. total messages per day or month per workspace).
  • Per-line limits:
    • Define how many messages a specific line can send in a day.
Workers enforce per-line limits; the app enforces workspace-level plan constraints.
Together, they ensure:
  • No single line is overused.
  • Entire workspaces stay within contracted limits.

​
Data Privacy & Isolation

Workspaces provide logical isolation:
  • Each workspace has its own:
    • Leads.
    • Campaigns.
    • Messages.
    • Lines and configuration.
Access decisions are always scoped by:
  • The workspace associated with the authenticated user or API key.
Tuco does not allow cross-workspace reads or writes via public APIs.
Operational behavior depends on contractual and legal requirements; in general:
  • Access to data by Tuco personnel is restricted and audited.
  • Where sensitive environments require it, additional controls can be applied via:
    • Support agreements.
    • Data processing addenda.
For compliance-specific guarantees (e.g. SOC 2, GDPR), refer to your contract and official legal/compliance documentation provided by Tuco outside of this developer guide.