Authentication

Create a HUMAIN Voice API key, keep it on your server, and send it correctly on every transport.

Get an API key

Sign in to the HUMAIN Voice console, open API keys, and select New key. Enter a Name after the service that uses it, select Create key, then copy the secret. The console shows it only once. New keys get your account's default scopes, which cover every workflow except Voice Agent: starting a session needs the opt-in agent scope, which you enable on the key (open the key under API keys). A key works only with the API_URL of the environment that issued it.

Use the key only from server-side code; browser and mobile apps expose it. Keep it out of source control, URLs, and logs.

Send the key: REST and HTTP streaming

Send the key in the x-api-key header on every batch REST and HTTP streaming request. No Origin header is needed.

curl -sS -X POST "$API_URL/v1/transcribe/codeswitch" \
  -H "x-api-key: $API_KEY" \
  -F "[email protected]"

Send the key: Socket.IO

The Socket.IO handshake needs two headers: x-api-key, and Origin set to the scheme and host of API_URL. The SDK sets both from api_url and api_key. A direct client sets them itself:

import { io } from "socket.io-client";

const socket = io(process.env.API_URL!, {
  path: process.env.API_PATH ?? "/socket.io",
  transports: ["websocket"],
  extraHeaders: {
    "x-api-key": process.env.API_KEY!,
    Origin: new URL(process.env.API_URL!).origin,
  },
});

Connection settings

VariableRequiredValue
API_URLYesYour environment's API origin: https://api.voice.humain.com.
API_KEYYesYour key from the HUMAIN Voice console.
API_PATHNoSocket.IO path. Defaults to /socket.io for every Socket.IO workflow. Set /realtime/socket.io only on the legacy sautech.humain.com endpoint.
API_VERSIONNoBatch REST version. Defaults to v1. Used by the SDK batch client.

Check your key

This request sends no file, so it creates no job:

curl -sS -X POST "$API_URL/v1/transcribe/codeswitch" \
  -H "x-api-key: $API_KEY" \
  -w '\nHTTP %{http_code}\n'
ResultMeaning
400 VALIDATION_INVALID_FORMATThe key works. The 400 is expected: no file was sent.
401The key is missing, mistyped, revoked, expired, or is from another environment.
403The key lacks batch access, or a gateway rejected the request.
Any other statusSee Error codes.

Authentication errors

ResponseMeaningFix
401 AUTH_UNAUTHORIZEDThe key is missing or invalid.Check that your server sends API_KEY as x-api-key, and check the key's status in API keys. Don't retry unchanged.
403 AUTH_FORBIDDENThe key lacks the scope for this operation.Open the key in API keys and check Scopes.
403 without an ErrorResponse bodyA gateway rejected the request.Check API_URL, the route, and the headers. On Socket.IO, check Origin.

On Socket.IO, an invalid key fails the connection (connect_error) or triggers an error event. Stop sending audio, fix the settings, and then reconnect. For other codes, see Error codes.

If a key is exposed

Treat a key as exposed if it appears in source control, client code, a URL, a log, or a message. Deleting the visible copy doesn't make it safe.

  1. In the HUMAIN Voice console, go to API keys, open the key, select Revoke, choose Leaked / compromised as the reason, and select Revoke key. Revoking is permanent; the key stops working within about a minute.
  2. Create a new key, store it in your secret manager, and redeploy every service that used the old one.
  3. On the Usage page, check the per-key table for activity you don't recognize.

To replace a key that isn't exposed, select Rotate. The console shows the new secret once; the old one keeps working for up to a minute.

Next steps

On this page