BYOK Setup

Bring Your Own Key (BYOK) allows you to use your own API keys for AI providers, giving you control over costs and access to specific models.

Supported Providers

Step 1: Get Your API Keys

Deepgram (STT)

1. Sign up at https://console.deepgram.com
2. Create an API key with "Member" role
3. Copy the key (it won't be shown again)

OpenAI (LLM)

1. Go to https://platform.openai.com/api-keys
2. Click "Create new secret key"
3. Copy the key (starts with sk-)

ElevenLabs (TTS)

1. Go to https://elevenlabs.io/app/settings/api-keys
2. Click "Create API Key"
3. Copy the key

Resend (Email)

1. Go to https://resend.com/api-keys
2. Click "Create API Key"
3. Copy the key (starts with re_)

Step 2: Add BYOK Configuration

Add your API key via the API:

curl -X POST https://api.hmsovereign.com/api/v1/byok \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "api_key": "sk-..."
  }'

Repeat for each provider you want to configure.

Step 3: Verify Configuration

Check which providers are configured:

curl https://api.hmsovereign.com/api/v1/byok \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "byok_keys": {
    "deepgram_secret_id": "vault-id-1",
    "openai_secret_id": "vault-id-2",
    "elevenlabs_secret_id": null,
    "resend_secret_id": null
  }
}

A non-null value means the provider is configured.

Step 4: Configure Your Assistant

Create or update your assistant to use the provider:

curl -X POST https://api.hmsovereign.com/api/v1/assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Assistant",
    "stt_config": {
      "provider": "deepgram",
      "model": "nova-3-general",
      "language": "nl"
    },
    "llm_config": {
      "provider": "openai",
      "model": "gpt-4o",
      "temperature": 0.7,
      "messages": [...]
    },
    "tts_config": {
      "provider": "elevenlabs",
      "voice_id": "your-voice-id"
    }
  }'

Available Models

Check available models for each provider:

curl https://api.hmsovereign.com/api/v1/byok/config \
  -H "Authorization: Bearer YOUR_API_KEY"

Important Notes for ElevenLabs

When using ElevenLabs with BYOK:

1. Voice Library Only - You only have access to voices in your ElevenLabs Voice Library
2. No Public Voices - You don't automatically get access to all public ElevenLabs voices
3. Add Voices First - Before using a voice, add it to your library at https://elevenlabs.io/app/voice-library
4. Voice IDs - Use the voice ID from your ElevenLabs dashboard

Removing BYOK Configuration

To remove a provider and go back to HMS Sovereign's default keys:

curl -X DELETE https://api.hmsovereign.com/api/v1/byok \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai"
  }'

Security

• API keys are stored securely and encrypted at rest
• Keys are never exposed in API responses
• Only encrypted references are stored in your account
• You can rotate keys at any time by adding a new key for the same provider

See BYOK API Reference for complete details.