Docs index: /llms.txt · every page as Markdown: add .md

Docs
Console Discord Get API secret
‹ Overview

Your API secret

The one credential for every bitHuman surface, and where each platform reads it.

Creator plan or higher

View as Markdown Open in ChatGPT Open in Claude

One API secret works for the REST API, the CLI, Python, Swift, Android and LiveKit. It needs a bitHuman account on the Creator plan or higher (pricing); the live demo and the web embed need none.

Get one

Create an API secret under Developer → API Secrets, then export it:

export BITHUMAN_API_SECRET="<your API secret>"
curl -s -X POST https://api.bithuman.ai/v1/validate -H "api-secret: $BITHUMAN_API_SECRET"
# → {"valid":true}

Where each platform reads it

PlatformEnvironmentIn code
REST API—header api-secret
CLIBITHUMAN_API_SECRETbithuman login stores a credential for you
PythonBITHUMAN_API_SECRET (read by bithuman.open)api_secret= on AsyncBithuman.create() only; bithuman.open() reads the environment
AppleBITHUMAN_API_SECRETEssence2Credential.set / Expression2Credential.set
Android—Essence2Credential.set(secret) / Expression2Credential.set(secret) before fetch() and create(); fetch the secret from your backend in a shipped app
LiveKit workerBITHUMAN_MASTER_SECRET, never BITHUMAN_API_SECRETa short-lived token minted from it, never the secret (LiveKit)
Web embed—none for a public agent; an embed token for a private one

Keep it safe

  • Keep the secret in the environment or a secrets manager, never in source control or on a command line.
  • Browsers and LiveKit rooms get short-lived tokens: an embed token or a runtime token minted with POST /v1/runtime-tokens/mint.
  • If a secret leaks, create a new one and delete the old one in the console.

What a shipped app holds

The Swift package and the Android SDK authenticate with your API secret, so every copy of an app you distribute carries it. Treat that secret as exposed: whoever extracts it can call the API as your account, spend your credits and create more secrets.

  • Fetch the secret from your backend when the app starts. Never compile it into a build you ship.
  • Give each app its own secret, so you can rotate one without touching the others (API secrets).
  • Watch your balance, and rotate the secret at once if usage looks wrong.

Next