Skip to main content

​
Pick auth by trust boundary, not convenience.

Callaro supports JWT, tenant API keys, partner API keys, and runtime server keys. The right choice depends on whether the caller acts for one tenant, many tenants, or internal runtime services.

JWT

Best for user-interactive operations in the Callaro app. Subject to app role and JWT-only controller guards.

Tenant API key

Best for server integrations that operate inside a single tenant and need explicit scope control.

Partner API key

Best for platform partners managing tenant provisioning and delegated operations across tenants.

​
Header patterns

curl "https://api.callaro.ai/api/v1/agents" \
  -H "Authorization: Bearer $CALLARO_JWT"

​
Decision table

Integration scenarioRecommended authWhy
Internal operator using Callaro UIJWTUses app session/role model and JWT-only guards.
Tenant backend sync job (CRM, BI, exports)Tenant API keyTenant-scoped, explicit least-privilege scopes.
Multi-tenant partner provisioning flowPartner API keySupports partner namespace and delegated tenant actions.
Runtime service-to-service internal callRuntime server keyServer-only routes, not customer-issued API keys.

​
Scope model (source: API key permission matrix)

Scopes are granted per key and mapped to route families. Examples:
  • bulk_call_campaigns:read and bulk_call_campaigns:write
  • contacts:read and contacts:write
  • phone_numbers:read and phone_numbers:write
  • voice_sessions:read
  • billing:tenant:read and billing:partner:read
Some scopes are opt-in and intentionally excluded from defaults, including billing:partner:allocate and call_traces:admin_read.

​
X-Tenant-Id semantics

When using partner APIs that operate on behalf of a downstream tenant, include X-Tenant-Id when required by that route family to select the effective tenant context.
Do not use X-Tenant-Id to bypass scope restrictions. The effective action is still gated by partner key permissions and route-level authorization.

​
Least-privilege rollout pattern

1

Start with read-only scopes

Create a dedicated key for observability and dry-run operations first.
2

Add write scopes only for required route families

Split campaign write operations from billing or contact-compliance scopes to reduce blast radius.
3

Use separate keys per environment and workload

Keep sandbox and production keys isolated, and rotate keys tied to specific services.
4

Review keys quarterly

Remove stale scopes, revoke unused keys, and validate service ownership.
Empty or omitted scopes should not be treated as “allow all.” Use explicit scopes and audit them against the permissions matrix before go-live.