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 inx-api-keyis refused with401, and sending both a partner key and anx-api-keyreturns400conflicting_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.
| Scope | Allows |
|---|---|
tenants:read | List and read tenants |
tenants:write | Create, update, suspend, resume, delete and restore tenants, and set tenant spend caps |
resources:read | Read agents, call flows, node flows, knowledge bases, numbers, call history, workflows and recordings in tenants |
resources:write | Create, change and delete those resources |
calls:write | Start outbound calls, web calls and batch calls, and run or activate workflows |
numbers:write | Buy, register and release phone numbers (buying costs money) |
events:read | Read the event log and webhook endpoints |
webhooks:write | Manage webhook endpoints, rotate secrets, send test events and redeliver events |
usage:read | Read usage |
templates:read / templates:write | Reserved for templates (planned). No endpoint uses them yet. |
sessions:write | Reserved 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
404tenant_not_foundfor any other tenant on/partner/v1routes, and403tenant_not_allowedon standard routes; - cannot manage webhook endpoints (
403key_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:
POST /v2/api/node-graphscreates 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 modelplatform-llmunless the body names another allowed model inllmModel(an unknown model returns400LLM_MODEL_INVALID), and the call flow starts with speech responsiveness 10 and interruption sensitivity 5.5.- Edit it with
PUT /v2/api/node-graphs/{id}orPATCH /v2/api/node-graphs/{id}/draft, and check it withPOST /v2/api/node-graphs/{id}/validate. POST /v2/api/node-graphs/{id}/publishmakes it live. A flow must be published before it can take calls.GET /v2/api/node-graphs/{id}returns the flow withpathway, which holds the call flow ID (pathway._id) and the agent (pathway.agent, whose_idis the agent ID).PUT /v1/api/agents/{agentId}sets the agent's voice, language, model and other agent settings.PATCH /partner/v1/tenants/{tenantId}/call-flows/{callFlowId}/settingssets the greeting, speech timing, recording and call handling timers. See Call flow settings.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
| Method | Path | Scope |
|---|---|---|
GET | /v1/api/agents | resources:read |
GET | /v1/api/agents/{agentId} | resources:read |
GET | /v1/api/agents/available | resources:read |
POST | /v1/api/agents | resources: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/voices | resources:read |
POST | /v1/api/agents/voices/search | resources:read |
POST | /v1/api/agents/voices/preview | resources:read |
POST | /v1/api/agents/voices/cartesia/preview | resources:read |
Node flows
| Method | Path | Scope |
|---|---|---|
GET | /v2/api/node-graphs | resources:read |
GET | /v2/api/node-graphs/templates | resources:read |
GET | /v2/api/node-graphs/{id} | resources:read |
POST | /v2/api/node-graphs | resources:write |
PUT | /v2/api/node-graphs/{id} | resources:write |
PATCH | /v2/api/node-graphs/{id}/draft | resources:write |
DELETE | /v2/api/node-graphs/{id}/draft | resources:write |
POST | /v2/api/node-graphs/{id}/validate | resources:read |
POST | /v2/api/node-graphs/{id}/simulate | resources:read |
POST | /v2/api/node-graphs/{id}/publish | resources:write |
POST | /v2/api/node-graphs/{id}/apply-live | resources:write |
GET | /v2/api/node-graphs/{id}/versions | resources:read |
POST | /v2/api/node-graphs/{id}/versions/{version}/restore | resources:write |
GET | /v2/api/node-graphs/{id}/runs | resources:read |
GET | /v2/api/node-graphs/{id}/runs/{runId} | resources:read |
POST | /v2/api/node-graphs/{id}/test-code | resources:write |
POST | /v2/api/node-graphs/{id}/duplicate | resources:write |
POST | /v2/api/node-graphs/{id}/archive | resources:write |
DELETE | /v2/api/node-graphs/{id} | resources:write |
Call flows
| Method | Path | Scope |
|---|---|---|
GET | /v1/api/call-flows | resources:read |
GET | /v1/api/call-flows/{id} | resources:read |
GET | /v1/api/call-flows/skill-prompt-defaults | resources:read |
GET | /v2/api/call-flows | resources:read |
GET | /v2/api/call-flows/metadata | resources:read |
GET | /v1/api/call-flows/{id}/drafts | resources:read |
PATCH | /v1/api/call-flows/{id}/drafts/{draftId} | resources:write |
POST | /v1/api/call-flows/{id}/drafts/{draftId}/activate | resources:write |
POST | /v1/api/call-flows/{id}/drafts/{draftId}/restore | resources:write |
POST | /v1/api/call-flows/{id}/drafts/deactivate | resources:write |
DELETE | /v1/api/call-flows/{id}/drafts/{draftId} | resources:write |
PATCH | /v1/api/call-flows/{id}/archive | resources:write |
PATCH | /v1/api/call-flows/{id}/restore | resources:write |
DELETE | /v1/api/call-flows/{id} | resources:write |
Knowledge bases
| Method | Path | Scope |
|---|---|---|
GET | /v1/api/knowledgebase | resources:read |
GET | /v1/api/knowledgebase/paginated | resources:read |
GET | /v1/api/knowledgebase/limits | resources:read |
GET | /v1/api/knowledgebase/workspace-usage | resources:read |
GET | /v1/api/knowledgebase/{id} | resources:read |
GET | /v1/api/knowledgebase/{id}/text | resources:read |
GET | /v1/api/knowledgebase/{id}/usage | resources:read |
GET | /v1/api/knowledgebase/{id}/files/presigned-url | resources:read |
GET | /v1/api/knowledgebase/{id}/files/proxy | resources:read |
POST | /v1/api/knowledgebase | resources:write |
PUT | /v1/api/knowledgebase/{id} | resources:write |
POST | /v1/api/knowledgebase/{id}/text | resources:write |
POST | /v1/api/knowledgebase/{id}/files | resources:write |
DELETE | /v1/api/knowledgebase/knowledgeBases/{knowledgeBaseId}/files/{fileName} | resources:write |
DELETE | /v1/api/knowledgebase/{id} | resources:write |
Phone numbers
| Method | Path | Scope |
|---|---|---|
GET | /v1/api/twilio/available-countries | resources:read |
GET | /v1/api/twilio/available-numbers | resources:read |
GET | /v1/api/twilio/phone-number-price | resources:read |
GET | /v1/api/twilio/user-phone-numbers | resources:read |
GET | /v1/api/twilio/user-phone-number-by-phone-number | resources:read |
GET | /v1/api/twilio/phone-numbers/{phoneNumberId}/config | resources:read |
PUT | /v1/api/twilio/phone-numbers/{phoneNumberId}/config | resources:write |
PUT | /v1/api/twilio/phone-numbers/{phoneNumberId}/config-messages | resources:write |
Buying, registering and releasing numbers use the Trillet OEM number endpoints, not the standard purchase endpoint.
Calls
| Method | Path | Scope |
|---|---|---|
POST | /v1/api/call | calls:write |
POST | /v1/api/calls/call | calls:write |
POST | /v1/api/calls/web/connect | calls:write |
POST | /v1/api/calls/web/disconnect | calls:write |
Use POST /v1/api/call for outbound calls. See Start an outbound call.
Batch calls
| Method | Path | Scope |
|---|---|---|
GET | /v1/api/batch-calls/template | resources:read |
POST | /v1/api/batch-calls/validate | resources:read |
POST | /v1/api/batch-calls/preview | resources:read |
POST | /v1/api/batch-calls/schedule-preview | resources:read |
POST | /v1/api/batch-calls | calls:write |
GET | /v1/api/batch-calls/{batchId} | resources:read |
GET | /v1/api/batch-calls/{batchId}/status | resources:read |
GET | /v1/api/batch-calls/{batchId}/calls | resources:read |
GET | /v1/api/batch-calls/{batchId}/calls/{jobId} | resources:read |
GET | /v1/api/batch-calls/{batchId}/export-results | resources: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
| Method | Path | Scope |
|---|---|---|
GET | /v1/api/call-history | resources:read |
GET | /v2/api/call-history | resources:read |
GET | /v2/api/call-history/{callHistoryId} | resources:read |
GET | /v2/api/call-history/resolve/{callId} | resources:read |
GET | /v2/api/call-history/metrics | resources:read |
GET | /v2/api/call-history/metrics/daily | resources:read |
GET | /v2/api/call-history/phonebook | resources:read |
GET | /v2/api/call-history/filter-options | resources:read |
POST | /v2/api/call-history/export-csv | resources: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
| Method | Path | Scope |
|---|---|---|
GET | /v1/api/workflows | resources:read |
GET | /v1/api/workflows/{id} | resources:read |
POST | /v1/api/workflows | resources:write |
PUT | /v1/api/workflows/{id} | resources:write |
DELETE | /v1/api/workflows/{id} | resources:write |
POST | /v1/api/workflows/{id}/duplicate | resources:write |
POST | /v1/api/workflows/{id}/pause | resources:write |
POST | /v1/api/workflows/{id}/test | resources:write |
POST | /v1/api/workflows/{id}/activate | calls:write |
POST | /v1/api/workflows/{id}/run | calls:write |
GET | /v1/api/workflows/{id}/runs | resources:read |
GET | /v1/api/workflows/runs/{runId} | resources:read |
POST | /v1/api/workflows/runs/{runId}/cancel | resources:write |
POST | /v1/api/workflows/runs/{runId}/retry | calls:write |
GET | /v1/api/workflows/schedule-preview | resources:read |
GET | /v1/api/workflows/{id}/webhook-sample | resources:read |
GET | /v1/api/workflows/phone-numbers | resources:read |
GET | /v1/api/workflows/pathways | resources:read |
GET | /v1/api/workflows/{workflowId}/live | resources:read |
Workspace secrets
| Method | Path | Scope |
|---|---|---|
GET | /v2/api/workspaces/secrets | resources:read |
POST | /v2/api/workspaces/secrets | resources: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. UseGET /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" }
}'
tostringrequiredThe number to call, in E.164 format. Anything else returns 400 INVALID_PHONE_NUMBER.
call_agent_idstringrequiredThe agent to call with. Required unless you send call_flow_id instead. The agent's call flow must be live.
call_flow_idstringA 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_idstringThe tenant number to call from. When omitted, one of the agent's numbers is chosen automatically.
dynamic_variablesobjectA flat key-value object of variables for the call, for example {"customer_name": "Sam"}. Arrays are refused.
metadataobjectYour own data, stored with the call.
callback_urlstringA URL to receive webhook events about this call.
reject_outside_hoursbooleantrue 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
| Status | Code | Meaning |
|---|---|---|
400 | conflicting_credentials | Both a partner key and an x-api-key were sent |
400 | tenant_required | A standard endpoint was called without x-workspace-id |
400 | invalid_tenant | x-workspace-id is not a valid tenant ID |
401 | partner_key_required | A /partner/v1 route was called with a user session or user API key instead of a partner key |
401 | invalid_api_key | The key is unknown or revoked |
401 | partner_not_enabled | Trillet OEM is not enabled for this account |
403 | missing_scope | The key lacks the scope this endpoint needs |
403 | route_not_available | The standard endpoint is not available to partner keys |
403 | tenant_not_allowed | The key is restricted and this tenant is not in its list (standard endpoints) |
404 | tenant_not_found | The tenant does not exist or is not yours |
429 | rate_limited | Too 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