Capability Groups

Capability Groups are the permission grants of the TrueTone API and the TrueTone Connector. Every endpoint and every Connector tool belongs to exactly one group. A key is issued with a set of groups and can never act outside them; the Connector exposes to your assistant only the tools your account’s groups allow.

The groups

This catalog renders live from the API, so the names and descriptions here are the ones the API itself enforces and returns in error messages.

Who can hold what

Your account role caps which groups a key can carry. The matrix below is the live one:

Roles in short: an individual owner runs their own account, an enterprise seat is a loan officer on a company account, and an org admin administers a company account. Only org admins can hold the Organization group.

What each endpoint requires

How enforcement behaves

A key without the group gets a 403 that names it. The body carries both the human name and the machine id, so your code can branch on requiredCapability:

{
  "error": "This API key does not grant the Voice transform capability",
  "requiredCapability": "voice"
}

Role-sensitive groups are re-checked live. A key freezes its groups at issuance, but for groups that depend on your role (today, the Organization group) the API re-reads your live account role on every call. If an admin is demoted, their org-scoped key stops working immediately, with a distinct message:

{
  "error": "Your TrueTone account role no longer includes the Organization capability",
  "requiredCapability": "org"
}

Re-minting the key cannot fix that one; only the role can.

A key with no recognized groups fails authentication. If a key’s stored groups contain nothing the API recognizes, it answers the uniform 401 rather than a 403, so it behaves exactly like an invalid key.