Authentication

How it works

All API requests to Shunyalabs authenticate using a Bearer token. The token is your API key, obtained from the Shunyalabs dashboard. Every HTTP request and WebSocket handshake must include an Authorization header.

Authorization header

Include the header in every HTTP request:

Authorization: Bearer <API_KEY>

curl -X POST https://asr.shunyalabs.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer <API_KEY>" \
  -F "model=zero-indic" \
  -F "[email protected]"

import os
# Set the environment variable before running:
# export SHUNYALABS_API_KEY="your-api-key"

from shunyalabs import AsyncShunyaClient

# Reads SHUNYALABS_API_KEY from env automatically
client = AsyncShunyaClient()

# Or pass the key directly
client = AsyncShunyaClient(api_key="your-api-key")

WebSocket authentication

For the streaming WebSocket endpoint, pass the API key in the Authorization header of the initial HTTP upgrade request:

GET wss://asr.shunyalabs.ai/ws HTTP/1.1
Host: asr.shunyalabs.ai
Authorization: Bearer <API_KEY>
Upgrade: websocket

The Python SDK handles this automatically when you call client.asr.stream(). If the key is invalid, the server emits an ERROR event and closes the connection immediately.

Authentication errors

In the Python SDK these map to AuthenticationError and PermissionDeniedError, both inheriting from ShunyalabsError:

from shunyalabs.exceptions import AuthenticationError, PermissionDeniedError

try:
    result = await client.asr.transcribe("audio.wav", config=config)
except AuthenticationError:
    print("Invalid or missing API key — check SHUNYALABS_API_KEY")
except PermissionDeniedError:
    print("API key does not have permission for this resource")

Security best practices

• Never hardcode API keys in source code or commit them to version control.
• Use .env files locally and a secrets manager (AWS Secrets Manager, GCP Secret Manager) in production.
• Add .env to .gitignore to prevent accidental commits.
• Rotate keys immediately if compromised — generate a new key from the dashboard and update all deployments.