Trillet AI logo

Trillet OEM authentication

Trillet OEM partner keys, scopes, tenant restrictions, and calling standard endpoints on behalf of a tenant.

Early access. Trillet OEM is built and in testing with design partners. Contact your account manager to have it enabled for your account. Details may still change.

Partner keys

Every Trillet OEM request is authenticated with a partner key, sent as a bearer token in the Authorization header:

curl https://api.trillet.ai/partner/v1/key \
  -H "Authorization: Bearer tpk_live_..."
  • Keys start with tpk_live_.
  • A key is shown once, when you create it. Trillet stores only a hash, so a lost key cannot be recovered. Create a new one and revoke the old one.
  • Keys are created and revoked in the OEM API section of your account settings, by an owner or admin of your partner account. Each key shows its name, prefix, scopes, allowed tenants and when it was last used.
  • A key acts as your partner account, not as a person, so it keeps working when staff leave. Keys do not expire. Revoking a key takes effect immediately.
  • An account can hold up to 50 active keys.
  • Send a partner key only in Authorization. Sending it in x-api-key is refused with 401, and sending both a partner key and an x-api-key returns 400 conflicting_credentials.

Treat partner keys like passwords. Keep them on your server, never in a browser or mobile app.

Check a key

GET /partner/v1/key returns the key's mode, scopes, tenant restriction and your partner account. It needs no scope.

{
  "object": "partner_key",
  "id": "b3b3b3b3b3b3b3b3b3b3b3b3",
  "mode": "live",
  "scopes": ["tenants:read", "tenants:write", "resources:read", "usage:read"],
  "tenantIds": [],
  "partner": {
    "id": "b0b0b0b0b0b0b0b0b0b0b0b0",
    "name": "Example Health",
    "maxTenants": 100,
    "tenantCount": 12
  }
}

maxTenants is the number of tenants your account may hold. Ask your account manager to raise it.

tenantCount is the number of tenants counted against maxTenants: every tenant your account holds that is active, suspended or provisioning_failed. It goes up when a tenant is created or restored and down when one is deleted, so deleted tenants are not counted, even while they can still be restored. It covers your whole account, not only the tenants a restricted key can see.

Scopes

Give each key only the scopes it needs. A new key has every scope unless you choose fewer.

ScopeAllows
tenants:readList and read tenants
tenants:writeCreate, update, suspend, resume, delete and restore tenants, and set tenant spend caps
resources:readRead agents, call flows, node flows, knowledge bases, numbers, call history, workflows and recordings in tenants
resources:writeCreate, change and delete those resources
calls:writeStart outbound calls, web calls and batch calls, and run or activate workflows
numbers:writeBuy, register and release phone numbers (buying costs money)
events:readRead the event log and webhook endpoints
webhooks:writeManage webhook endpoints, rotate secrets, send test events and redeliver events
usage:readRead usage
templates:read / templates:writeReserved for templates (planned). No endpoint uses them yet.
sessions:writeReserved for embedding (planned). No endpoint uses it yet.

Restricting a key to some tenants

A key can be restricted to a list of tenants, for example a key used by one regional team. A restricted key:

  • sees only those tenants in lists, usage and the event log;
  • gets 404 tenant_not_found for any other tenant on /partner/v1 routes, and 403 tenant_not_allowed on standard routes;
  • cannot manage webhook endpoints (403 key_restricted), because endpoints receive events for every tenant.

Calling standard endpoints for a tenant

A partner key can call a set of standard API endpoints on behalf of one of its tenants. Send the tenant ID in x-workspace-id:

curl https://api.trillet.ai/v1/api/agents \
  -H "Authorization: Bearer tpk_live_..." \
  -H "x-workspace-id: d9d9d9d9d9d9d9d9d9d9d9d9"

Access is deny by default. Only the endpoints below are available to partner keys, each with the scope shown. Any other standard endpoint returns 403 route_not_available.

Building an agent

Today a partner builds a tenant's agent through node flows:

  1. POST /v2/api/node-graphs creates the node flow together with its agent and call flow. The flow starts as a draft. With a partner key, the new agent uses the model platform-llm unless the body names another allowed model in llmModel (an unknown model returns 400 LLM_MODEL_INVALID), and the call flow starts with speech responsiveness 10 and interruption sensitivity 5.5.
  2. Edit it with PUT /v2/api/node-graphs/{id} or PATCH /v2/api/node-graphs/{id}/draft, and check it with POST /v2/api/node-graphs/{id}/validate.
  3. POST /v2/api/node-graphs/{id}/publish makes it live. A flow must be published before it can take calls.
  4. GET /v2/api/node-graphs/{id} returns the flow with pathway, which holds the call flow ID (pathway._id) and the agent (pathway.agent, whose _id is the agent ID).
  5. PUT /v1/api/agents/{agentId} sets the agent's voice, language, model and other agent settings.
  6. PATCH /partner/v1/tenants/{tenantId}/call-flows/{callFlowId}/settings sets the greeting, speech timing, recording and call handling timers. See Call flow settings.
  7. POST /v1/api/agents/{agentId}/bind/{phoneNumberId} assigns a number. See Phone numbers.

Creating and updating simple prompt call flows (POST and PUT /v1/api/call-flows) is not available to partner keys yet.

Available endpoints

Agents

MethodPathScope
GET/v1/api/agentsresources:read
GET/v1/api/agents/{agentId}resources:read
GET/v1/api/agents/availableresources:read
POST/v1/api/agentsresources:write
PUT/v1/api/agents/{agentId}resources:write
DELETE/v1/api/agents/{agentId}resources:write
POST/v1/api/agents/{agentId}/bind/{phoneNumberId}resources:write
POST/v1/api/agents/{agentId}/release/{phoneNumberId}resources:write
GET/v1/api/agents/voicesresources:read
POST/v1/api/agents/voices/searchresources:read
POST/v1/api/agents/voices/previewresources:read
POST/v1/api/agents/voices/cartesia/previewresources:read

Node flows

MethodPathScope
GET/v2/api/node-graphsresources:read
GET/v2/api/node-graphs/templatesresources:read
GET/v2/api/node-graphs/{id}resources:read
POST/v2/api/node-graphsresources:write
PUT/v2/api/node-graphs/{id}resources:write
PATCH/v2/api/node-graphs/{id}/draftresources:write
DELETE/v2/api/node-graphs/{id}/draftresources:write
POST/v2/api/node-graphs/{id}/validateresources:read
POST/v2/api/node-graphs/{id}/simulateresources:read
POST/v2/api/node-graphs/{id}/publishresources:write
POST/v2/api/node-graphs/{id}/apply-liveresources:write
GET/v2/api/node-graphs/{id}/versionsresources:read
POST/v2/api/node-graphs/{id}/versions/{version}/restoreresources:write
GET/v2/api/node-graphs/{id}/runsresources:read
GET/v2/api/node-graphs/{id}/runs/{runId}resources:read
POST/v2/api/node-graphs/{id}/test-coderesources:write
POST/v2/api/node-graphs/{id}/duplicateresources:write
POST/v2/api/node-graphs/{id}/archiveresources:write
DELETE/v2/api/node-graphs/{id}resources:write

Call flows

MethodPathScope
GET/v1/api/call-flowsresources:read
GET/v1/api/call-flows/{id}resources:read
GET/v1/api/call-flows/skill-prompt-defaultsresources:read
GET/v2/api/call-flowsresources:read
GET/v2/api/call-flows/metadataresources:read
GET/v1/api/call-flows/{id}/draftsresources:read
PATCH/v1/api/call-flows/{id}/drafts/{draftId}resources:write
POST/v1/api/call-flows/{id}/drafts/{draftId}/activateresources:write
POST/v1/api/call-flows/{id}/drafts/{draftId}/restoreresources:write
POST/v1/api/call-flows/{id}/drafts/deactivateresources:write
DELETE/v1/api/call-flows/{id}/drafts/{draftId}resources:write
PATCH/v1/api/call-flows/{id}/archiveresources:write
PATCH/v1/api/call-flows/{id}/restoreresources:write
DELETE/v1/api/call-flows/{id}resources:write

Knowledge bases

MethodPathScope
GET/v1/api/knowledgebaseresources:read
GET/v1/api/knowledgebase/paginatedresources:read
GET/v1/api/knowledgebase/limitsresources:read
GET/v1/api/knowledgebase/workspace-usageresources:read
GET/v1/api/knowledgebase/{id}resources:read
GET/v1/api/knowledgebase/{id}/textresources:read
GET/v1/api/knowledgebase/{id}/usageresources:read
GET/v1/api/knowledgebase/{id}/files/presigned-urlresources:read
GET/v1/api/knowledgebase/{id}/files/proxyresources:read
POST/v1/api/knowledgebaseresources:write
PUT/v1/api/knowledgebase/{id}resources:write
POST/v1/api/knowledgebase/{id}/textresources:write
POST/v1/api/knowledgebase/{id}/filesresources:write
DELETE/v1/api/knowledgebase/knowledgeBases/{knowledgeBaseId}/files/{fileName}resources:write
DELETE/v1/api/knowledgebase/{id}resources:write

Phone numbers

MethodPathScope
GET/v1/api/twilio/available-countriesresources:read
GET/v1/api/twilio/available-numbersresources:read
GET/v1/api/twilio/phone-number-priceresources:read
GET/v1/api/twilio/user-phone-numbersresources:read
GET/v1/api/twilio/user-phone-number-by-phone-numberresources:read
GET/v1/api/twilio/phone-numbers/{phoneNumberId}/configresources:read
PUT/v1/api/twilio/phone-numbers/{phoneNumberId}/configresources:write
PUT/v1/api/twilio/phone-numbers/{phoneNumberId}/config-messagesresources:write

Buying, registering and releasing numbers use the Trillet OEM number endpoints, not the standard purchase endpoint.

Calls

MethodPathScope
POST/v1/api/callcalls:write
POST/v1/api/calls/callcalls:write
POST/v1/api/calls/web/connectcalls:write
POST/v1/api/calls/web/disconnectcalls:write

Use POST /v1/api/call for outbound calls. See Start an outbound call.

Batch calls

MethodPathScope
GET/v1/api/batch-calls/templateresources:read
POST/v1/api/batch-calls/validateresources:read
POST/v1/api/batch-calls/previewresources:read
POST/v1/api/batch-calls/schedule-previewresources:read
POST/v1/api/batch-callscalls:write
GET/v1/api/batch-calls/{batchId}resources:read
GET/v1/api/batch-calls/{batchId}/statusresources:read
GET/v1/api/batch-calls/{batchId}/callsresources:read
GET/v1/api/batch-calls/{batchId}/calls/{jobId}resources:read
GET/v1/api/batch-calls/{batchId}/export-resultsresources:read
DELETE/v1/api/batch-calls/{batchId}/calls/{jobId}resources:write
DELETE/v1/api/batch-calls/{batchId}/contacts/{phone}resources:write
DELETE/v1/api/batch-calls/{batchId}resources:write
GET/v1/api/batch-history/{batchHistoryId}resources:read
GET/v1/api/batch-history/batch/{batchId}resources:read
GET/v1/api/batch-history/workspace/{workspaceId}resources:read

Call history and recordings

MethodPathScope
GET/v1/api/call-historyresources:read
GET/v2/api/call-historyresources:read
GET/v2/api/call-history/{callHistoryId}resources:read
GET/v2/api/call-history/resolve/{callId}resources:read
GET/v2/api/call-history/metricsresources:read
GET/v2/api/call-history/metrics/dailyresources:read
GET/v2/api/call-history/phonebookresources:read
GET/v2/api/call-history/filter-optionsresources:read
POST/v2/api/call-history/export-csvresources:read
GET/v2/api/recordings/{callHistoryId}resources:read

GET /v2/api/recordings/{callHistoryId} returns the audio file for a call in the tenant, or 404 when the call has no recording. callHistoryId is the data.call.id in call events and the callHistoryId in per-call usage. The recording download on Trillet OEM returns the same file.

Workflows

MethodPathScope
GET/v1/api/workflowsresources:read
GET/v1/api/workflows/{id}resources:read
POST/v1/api/workflowsresources:write
PUT/v1/api/workflows/{id}resources:write
DELETE/v1/api/workflows/{id}resources:write
POST/v1/api/workflows/{id}/duplicateresources:write
POST/v1/api/workflows/{id}/pauseresources:write
POST/v1/api/workflows/{id}/testresources:write
POST/v1/api/workflows/{id}/activatecalls:write
POST/v1/api/workflows/{id}/runcalls:write
GET/v1/api/workflows/{id}/runsresources:read
GET/v1/api/workflows/runs/{runId}resources:read
POST/v1/api/workflows/runs/{runId}/cancelresources:write
POST/v1/api/workflows/runs/{runId}/retrycalls:write
GET/v1/api/workflows/schedule-previewresources:read
GET/v1/api/workflows/{id}/webhook-sampleresources:read
GET/v1/api/workflows/phone-numbersresources:read
GET/v1/api/workflows/pathwaysresources:read
GET/v1/api/workflows/{workflowId}/liveresources:read

Workspace secrets

MethodPathScope
GET/v2/api/workspaces/secretsresources:read
POST/v2/api/workspaces/secretsresources:write
PUT/v2/api/workspaces/secrets/{name}resources:write
PATCH/v2/api/workspaces/secrets/{name}resources:write
DELETE/v2/api/workspaces/secrets/{name}resources:write

Not available yet

These return 403 route_not_available to a partner key:

  • Creating and updating simple prompt call flows (POST /v1/api/call-flows, PUT /v1/api/call-flows/{id}). Build agents with node flows instead, and change basic settings with Call flow settings.
  • Call-flow draft writes other than those listed above: creating a draft, autosave and publishing a draft (.../drafts, .../drafts/autosave, .../drafts/{draftId}/publish), and every other call-flow route not in the table.
  • The /v1/api/calls/recordings/* routes. Use GET /v2/api/recordings/{callHistoryId} or the recording download.
  • Routes that take a target workspace in the body, such as duplicating or moving a flow to another workspace, and sharing.
  • Routes that take a user ID in the path.
  • Third-party credentials: Google, GHL, Meta, bring-your-own voice keys and Google Sheets export.
  • Public demo links, Slack and the prompt helper endpoints.
  • Account, billing, wallet, team members and roles, domains, and API key management.

Start an outbound call

POST /v1/api/call places an outbound call from one of the tenant's numbers. It needs calls:write.

curl -X POST https://api.trillet.ai/v1/api/call \
  -H "Authorization: Bearer tpk_live_..." \
  -H "x-workspace-id: d9d9d9d9d9d9d9d9d9d9d9d9" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15125550177",
    "call_agent_id": "e0e0e0e0e0e0e0e0e0e0e0e0",
    "dynamic_variables": { "customer_name": "Sam" },
    "metadata": { "crmLeadId": "L-1042" }
  }'
tostringrequired

The number to call, in E.164 format. Anything else returns 400 INVALID_PHONE_NUMBER.

call_agent_idstringrequired

The agent to call with. Required unless you send call_flow_id instead. The agent's call flow must be live.

call_flow_idstring

A call flow ID, accepted in place of call_agent_id. If you send both, they must refer to the same agent, or the request returns 400 AGENT_FLOW_MISMATCH.

from_phone_number_idstring

The tenant number to call from. When omitted, one of the agent's numbers is chosen automatically.

dynamic_variablesobject

A flat key-value object of variables for the call, for example {"customer_name": "Sam"}. Arrays are refused.

metadataobject

Your own data, stored with the call.

callback_urlstring

A URL to receive webhook events about this call.

reject_outside_hoursboolean

true refuses the call with 409 OUTSIDE_CALLING_HOURS when it is outside the flow's calling hours, instead of queueing it for the next calling window. The 409 response includes next_available_at and timezone.

A successful request returns status: "success" with call_agent_id, callId (the call history ID), roomName and jobId. The call is queued and dialled straight after. Refusals return status: "error" with message, error and, where there is one, code. A suspended tenant gets 403 workspace_suspended.

See Initiate outbound call for the full reference. POST /v1/api/calls/call is an older route that takes only agentId and toNumber. Use POST /v1/api/call, which validates the number and accepts the fields above.

A tenant that is not yours returns 404 tenant_not_found, so a key can never confirm another partner's tenant IDs. Your own partner account is not a tenant: a partner key cannot use it as x-workspace-id.

The partner key check uses the Trillet OEM error format. Once a request passes the check, the standard endpoint answers in its usual format.

Authentication errors

StatusCodeMeaning
400conflicting_credentialsBoth a partner key and an x-api-key were sent
400tenant_requiredA standard endpoint was called without x-workspace-id
400invalid_tenantx-workspace-id is not a valid tenant ID
401partner_key_requiredA /partner/v1 route was called with a user session or user API key instead of a partner key
401invalid_api_keyThe key is unknown or revoked
401partner_not_enabledTrillet OEM is not enabled for this account
403missing_scopeThe key lacks the scope this endpoint needs
403route_not_availableThe standard endpoint is not available to partner keys
403tenant_not_allowedThe key is restricted and this tenant is not in its list (standard endpoints)
404tenant_not_foundThe tenant does not exist or is not yours
429rate_limitedToo many invalid keys from your IP address in the last minute

Handle a 401 by its status, not only by error.code.

Last updated on