bitHuman docs
Status Get an API secret
Get startedPlatformsDeployModelsBuildAPIPerformance
Downloads & versionsChangelogPricing and creditsTroubleshootingFAQGlossarySupport & communityFor AI agentsStatus
Get an API secret →

Your API secret

More ▾
View as markdown Open in Claude ↗ Open in ChatGPT ↗

The one credential for every bitHuman surface: where to get it, where each platform reads it, and what a shipped app holds.

Creator plan or higher

One API secret works on every surface: the REST API, the CLI, Python, Apple, Android and LiveKit. Credits pay for session time, talking or idle, by the exact second (pricing).

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

BITHUMAN_API_KEY is a deprecated alias of BITHUMAN_API_SECRET; rename it. It stops being read in CLI 3.0 and bithuman 4.0 (no earlier than 2026-12-26).

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