​

Bring your own speech credentials (STT/TTS)

​

What BYO speech credentials are (and are not)

Register your own Cartesia (TTS) or Deepgram (STT) API key so voicemail-greeting synthesis and on-demand call transcription run against a credential and cost centre your organization owns. Until a key is active and enforced, the platform-owned key stays authoritative; revoking falls back to it immediately for new turns.

• Your account, your cost centre. Usage under your key bills to your provider account, not to Orbit. The key is stored encrypted at rest and is never echoed back; every read returns only a fingerprint.
• Your route stays inside your credential’s boundary. Traffic served by your key never hops into the platform failover chain mid-turn, and your key never joins the platform chain for any other organization.
• The platform key stays authoritative until your key is active and enforced. Registering alone changes nothing about live traffic. A key that is registered but not enforced is advisory.
• Revoke falls back immediately. Revoking clears enforcement and new turns use the platform-owned key right away. Turns already in flight finish on your credential.

​

Providers and scopes per kind

​

Dashboard walkthrough

​

Register a key

1. In the panel for the kind you want, select the Provider. Optionally set an Alias (for example, “ACME prod voice key”) and a Justification for your audit trail.
2. Paste the API key. It is never echoed back; only its fingerprint is stored.
3. Submit Register key. Orbit probes the key against the provider first. A key the provider refuses is rejected with the provider’s status, and nothing is saved.
4. A successful registration lands in Pending activation. Press Activate. With Enforce immediately checked (the default), the key becomes active and enforced in one step; uncheck it to activate first and enforce later while you verify output.

​

Read the state

​

Rotate

​

Revoke

​

API walkthrough

• GET /api/v1/voice/voice-provider-credential — both kinds’ current configs (null when unset), the provider catalog per kind, and the resolved posture. Read-only.
• PUT /api/v1/voice/voice-provider-credential/:kind — register. New registrations start pending.
• POST /api/v1/voice/voice-provider-credential/:kind/activate — mark a pending credential active; enforce: true begins routing through it.
• POST /api/v1/voice/voice-provider-credential/:kind/rotate — replace the secret, preserving lifecycle state.
• POST /api/v1/voice/voice-provider-credential/:kind/revoke — clear enforcement; new turns fall back to the platform key.

​

Register and enforce

curl -X PUT https://api.orbit.devotel.io/api/v1/voice/voice-provider-credential/stt \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "deepgram",
    "credential": "<your Deepgram API key>",
    "key_alias": "ACME prod voice key",
    "justification": "Move STT usage to our cost centre"
  }'

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

await orbit.request('PUT', '/voice/voice-provider-credential/stt', {
  provider: 'deepgram',
  credential: process.env.DEEPGRAM_API_KEY!,
  key_alias: 'ACME prod voice key',
});

curl -X POST https://api.orbit.devotel.io/api/v1/voice/voice-provider-credential/stt/activate \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "enforce": true }'

​

Probe-first semantics

{
  "error": {
    "code": "VOICE_CREDENTIAL_PROVIDER_REJECTED",
    "message": "Deepgram rejected this credential (HTTP 401). Check the key in your provider dashboard and try again.",
    "status": 422,
    "details": {
      "kind": "stt",
      "provider": "deepgram",
      "provider_status": 401
    }
  }
}

​

Rotate

curl -X POST https://api.orbit.devotel.io/api/v1/voice/voice-provider-credential/tts/rotate \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "provider": "cartesia", "credential": "<new Cartesia key>" }'

​

Read and revoke

​

Live-call behavior

• On-demand transcription of completed recordings runs against your Deepgram key while it is active and enforced, and against the platform key otherwise.
• The STT Playground compares providers using your active Deepgram key even before you enforce it, so you can verify transcription quality on your own account before routing production traffic.

​

Operations

• Rotation cadence. Rotate on whatever key-rotation schedule your provider policy sets. Because the replacement is probed before saving and rotation preserves the active/enforced state, a clean rotation has no fallback window. Track rotation_count in the panel or the GET response as your audit trail.
• Provider-side 401/403 during live use. A deterministic refusal surfaces rather than failing over. Check the key’s status and scope in the provider dashboard, then rotate in a valid replacement. Do not retry the same key; the verdict does not change until the key does.
• Incident fallback. If your provider has an outage and you want Orbit back on the platform key now, revoke. Enforcement clears immediately and new turns use the platform-owned key. Register afresh when you want BYO back.
• Rejected at write time. See Troubleshooting: voice inference credential rejected for the recovery checklist and what to include in a support ticket if a correctly scoped new key is still refused.

​

See also

• Troubleshooting: voice inference credential rejected — recover from VOICE_CREDENTIAL_PROVIDER_REJECTED.
• Transcription operations — day-to-day transcription operations, including the customer-managed credential boundary.
• Live call transcription — the platform STT chain and its failover rules.
• Voice Settings Consoles — the remaining org-level voice settings consoles.