Trovacast

Platform

Authentication and API keys

Every request carries an API key as a bearer token. Keys are scoped, revocable, checked on every call, and shown only once.

Send your key in the Authorization header of every request. There is no session, cookie or OAuth flow: the key is the credential, and it is checked again on each call.

An authenticated request (http)
GET /v1/me HTTP/1.1
Host: api.trovacast.com
Authorization: Bearer tc_live_…

Create a key

  1. Sign in to the Trovacast console as a project administrator and open Settings → Developers.
  2. Create a key, name it after the system that will use it ("Shop backend"), and tick only the scopes it needs. Optionally give it an expiry.
  3. Copy the secret. It is shown once, in the response that creates it — Trovacast keeps only a hash of it and cannot show it again.
  4. Store it where your server reads secrets (an environment variable or a secrets manager), never in browser or mobile code and never in a repository.

A key is tc_live_ followed by 40 random characters. Lists show a non-secret prefix (tc_live_ and four characters) and the last four characters, so keys can be told apart without revealing them. At most 25 keys can be live in a project at once.

Test mode

A test key (tc_test_…, the Mode field in Settings → Developers) works against the same project, but nothing it sends reaches a real provider and nothing it does is billed: messages go to the channel’s sandbox and calls are walked by the call sandbox (queued → ringing → in_progress → completed) without dialling, each firing the same webhooks a live one would, and everything it creates reads livemode: false. Every other rule — scopes, consent, windows — still runs. Channel setup does not hold a test send back: with no WhatsApp number, SMS settings, DLT registration or email domain, it goes from the platform’s test sender, and the message’s warnings say what a live send would still need (Try messaging before KYC). A test key creates test templates the sandbox reviews and runs test broadcasts to test contacts. Where nothing can be sandboxed (syncing templates from Meta, connecting WhatsApp, email domains, renting numbers, acting on a live call) a test key is 422 TEST_MODE_UNSUPPORTED.

The test-mode partition

A test key creates and reads its own test records and reads the project’s configuration, but it never reads live personal data, never changes live consent, never changes or erases a live record, and never receives a live event.

A test key
Calls, messages, conversations, broadcasts, eventsLists and reads the livemode: false ones only (a test conversation is a test contact’s thread or the sandbox’s); a live one is a 404. A live key, likewise, reads live records only. Test calls have a cap of their own (10 at once), apart from the live-call caps.
Live threadsReplies, reacts and quotes only in a test thread: a live customer’s conversation is 404 CONVERSATION_NOT_FOUND, and a live message 404 REPLY_TARGET_NOT_FOUND — what an unknown id gets — and nothing is written into it. A live key, likewise, gets the same 404 for a test thread or a test message.
TemplatesCreates and deletes its own test templates (livemode: false), which only test sends and test broadcasts use; lists its test templates and the live ones (each says which). A live template is 422 to change. A live key never sees a test template.
Recordings, contact exports422 TEST_MODE_UNSUPPORTED: a recording is a live call’s audio, and an export is unmasked.
Consent writesRecorded on the test contacts it created; on a live contact, 422 — consent is a real person’s. Consent recorded on a test contact never authorizes a live send. The first live traffic that uses the contact — a live write, a live message or call to it, or a real inbound message or call from its number — makes it a live contact for good (audited) and clears the opt-ins recorded in test mode; from then on its consent and conversation events are live. Reading consent works on any contact.
ContactsCreates a contact nobody holds yet — a test contact (livemode: false); changing, reviving or erasing an existing one is 422. Look an existing contact up with GET /v1/contacts?phone=, or send to the number directly.
Webhook endpointsEach endpoint has a mode. A test key sees, manages and creates test endpoints, which receive the events of test traffic only; live endpoints receive live events only.
Call flows, voice applications, AI agentsCreates its own (livemode: false), which run on test calls only — never a live call, a number’s route, a queue’s overflow, a campaign or a sequence — and changes only those. Live configuration is read-only to it, and a live flow may name only live applications and agents. Its AI-agent and external-agent calls are placed even while the project’s AI-call switch is off (a test call never reaches a carrier). A live key sees none of a test key’s configuration: it is not in a live key’s lists, and every route of it is 404, as an unknown id.
Business verificationFills in and submits the project’s real verification (verifications:write) — a project that holds only test keys gets verified this way. It is not test data; every change is audited against the key.

So you can build an IVR before your business is verified: create and publish a call flow with the test key and place test calls against it (mode: FLOW), with every call.* event on a test endpoint. Numbers are live inventory and route to live configuration only, so inbound calls are always live; recreate the flow with a live key once you are approved.

A project that signed up on its own holds test keys only until its business is verified; a live key is 403 LIVE_KEYS_REQUIRE_VERIFICATION until then.

Sandbox test numbers and addresses

With a test key, the sandbox decides what happens by the destination alone, so every failure your integration must handle can be scripted. Phone numbers (SMS, WhatsApp and calls) by their last four digits; any number in an allowed country works (for example +91 98765 4 followed by the four digits):

Number ends inSMS and WhatsAppCalls
0002Accepted, then failed (SMS SMS_CARRIER_BLOCKED, WhatsApp META_131026)Rings, then busy
0003Accepted, then no receipt ever arrives (stays sent)Rings, then no_answer
0004Refused: opted out (SMS SMS_OPTED_OUT, WhatsApp META_131050)Answered (as any other)
0005Refused: invalid number (SMS SMS_INVALID_NUMBER, WhatsApp META_100)failed before ringing (SANDBOX_INVALID_NUMBER)
0006Throttled once (the send is retried)Answered
0007Never confirmed (SUBMISSION_UNKNOWN)Answered
anything elseAccepted, then delivered (WhatsApp: then read)Answered, three seconds of talk, then completed

Email addresses by a +tag on the mailbox (any domain, e.g. you+bounce@example.com): +bounce — accepted, then failed (SES_BOUNCE_PERMANENT); +noreceipt — accepted, then nothing; +reject — refused (SES_REJECT); +throttle — throttled; +unknown — never confirmed (SUBMISSION_UNKNOWN); anything else — accepted, then delivered. Every outcome fires the webhooks a live one would.

Two kinds of key

KindActs inWho creates it
Project key (ORG)Exactly one project (organization). Every read is project-wide — there is no team or agent scoping.A project administrator in Settings → Developers, or an integration for a project it provisioned.
Integration key (INTEGRATION)No project. It provisions and administers only the projects its integration created, and never reads their data.Trovacast, for a platform partner. See Integration keys.

The two families never mix: a project endpoint refuses an integration key, and the reverse, with 403 API_KEY_KIND_MISMATCH — whatever scopes the key holds.

What is checked on every request

  • The key exists, is not revoked and has not expired.
  • A project key's project is active: a suspended or closed project's keys stop working.
  • An integration key's integration is active.
  • The key holds the scope the endpoint requires (else 403 API_KEY_SCOPE_MISSING, naming the scope in requiredScope).

Every failure of the first three — and a missing, malformed or unknown key — answers the same 401 API_KEY_INVALID, so a response never reveals whether a key ever existed or why it stopped working. Revoking a key, or suspending its project, takes effect on its very next request; reactivating does too.

Check a key: who am I?

GET /v1/me is open to every live key of either kind and tells you what the key is, which scopes it holds, and which project it acts in — the quickest way to confirm a deployment picked up the right key.

Introspect the key
curl 'https://api.trovacast.com/v1/me' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 OK (json)
{
  "kind": "ORG",
  "key": {
    "id": "API_KEY_ID",
    "name": "Shop backend",
    "prefix": "tc_live_AbCd",
    "last4": "x9Yz",
    "expiresAt": null
  },
  "scopes": [
    "contacts:read",
    "messages:write"
  ],
  "organization": {
    "id": "ORGANIZATION_ID",
    "name": "Acme"
  },
  "entitlements": {
    "calling": false,
    "messaging": true
  },
  "mintedByIntegration": null
}

An integration key gets integration: { id, slug, name } instead of organization and entitlements. entitlements says which product lines the project has: a call needs calling, a message messaging.

What a key did: the request log

GET /v1/me/requests lists the requests this key made in the last 7 days, newest first — method, route template, status, request id and latency. Filter by status (2xx, 3xx, 4xx, 5xx) to find what failed.

Recent failed requests
curl 'https://api.trovacast.com/v1/me/requests?status=4xx' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 OK (json)
{
  "data": [
    {
      "object": "api_request",
      "id": "API_REQUEST_ID",
      "method": "POST",
      "route": "/v1/messages",
      "status": 409,
      "requestId": "3b1f…",
      "durationMs": 41,
      "createdAt": "2026-10-28T10:00:00.000Z"
    }
  ],
  "nextCursor": null
}
  • route is the route template (/v1/contacts/:contactId), never the path with its ids; no query string and no body is kept, so the log holds nothing that names a person.
  • requestId is the one the response carried (the X-Request-Id header, and requestId on an error) — quote it to support.
  • Every request the key made once it authenticated is logged, refusals included. A request refused before the key was known (an invalid key, or the per-key rate limit) belongs to no key and is not.
  • Rows appear a few seconds after the response. A key sees only its own log.

Keeping keys safe

  • Give each system its own key with only the scopes it uses; a leaked key then exposes only that.
  • Call the API from your servers only. A key in a browser bundle or a mobile app is a published key.
  • To rotate, use Rotate key in Settings → Developers (or let a key with the api-keys:rotate scope replace itself with POST /v1/me/rotate): the new secret works at once, and the old one keeps working for the overlap you choose (24 hours by default, up to 7 days, or none) so you can deploy without downtime. Rename a key or take scopes away there too — a key never gains scopes; create a new one for that. Revocation is immediate.
  • Errors from the SDKs never carry the key, the request body or the URL, so they are safe to log.