‹ Overview
Your API secret
The one credential for every bitHuman surface, and where each platform reads it.
One API secret works for the REST API, the CLI, Python, Swift, Android and LiveKit. It needs a bitHuman account (sign up) on the Creator plan or higher (pricing). The live demo and embedding a public agent need none; creating your own agents needs the Creator plan.
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
| Platform | Environment | In code |
|---|---|---|
| REST API | — | header api-secret |
| CLI | BITHUMAN_ | bithuman login stores a credential for you |
| Python | BITHUMAN_ (read by bithuman.open) | api_secret= on AsyncBithuman. only; bithuman. reads the environment |
| Apple | BITHUMAN_ | Essence2Credential. / Expression2Credential. |
| Android | — | Essence2Credential. / Expression2Credential. before fetch() and create(); fetch the secret from your backend in a shipped app |
| LiveKit worker | the same API secret, set as BITHUMAN_ on the worker, never as BITHUMAN_ | rooms see only a 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 under Developer → API Secrets.
- Shipping a mobile or desktop app: Keep your API secret off the device.
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
- REST authentication: the header, validation and error codes.
- Pick your platform.