Authentication

Use your organization's approved access flow to obtain an API key and the connection values configured for your environment.

Before you begin

Have these prerequisites ready:

Obtain credentials

Obtain and configure these values through your organization's approved access flow:

• API_KEY: the credential for protected operations, with the speech capabilities your integration needs.
• API_URL: the service URL provisioned for the environment.
• API_PATH: an optional Socket.IO path override. The released SDK defaults to /socket.io; the legacy sautech.humain.com endpoint is not consolidated and still requires /realtime/socket.io.

Do not guess a URL or path from another environment. Use only the values configured for the environment where the integration runs.

Store credentials

For a local Bash session, set the non-secret values and read the key without echoing it or placing it in shell history:

export API_URL="https://api.voice.humain.com"
read -rsp "HUMAIN Voice API key: " API_KEY
export API_KEY
printf '\n'

In a deployed service, inject API_KEY from a secret manager or protected environment variable. Keep it out of source control, client-exposed environment variables, URLs, logs, screenshots, and support messages. Do not print the variable to confirm that it is set.

Set API_PATH only when your deployment overrides the SDK's /socket.io default. The legacy sautech.humain.com endpoint requires /realtime/socket.io. Batch REST does not use it.

Send Origin on Socket.IO

The Socket.IO handshake requires Origin even from non-browser clients that do not set it automatically. Send the scheme and host of the service URL provisioned for your environment.

SDK 0.18.0 derives Origin from api_url and sets it on the Socket.IO handshake. A direct Socket.IO client must send the header itself, set to the scheme and host of API_URL. Batch REST and Realtime HTTP require x-api-key; their published OpenAPI contract does not require Origin.

Run a non-mutating diagnostic

Check the configured route and credential without uploading audio or opening a stream.

Read a deliberately unknown Batch job

Read a syntactically valid job ID that is not associated with a real job:

curl -sS -i \
  "$API_URL/v1/transcribe/00000000-0000-4000-8000-000000000000" \
  -H "x-api-key: $API_KEY"

This request does not upload audio or create a job. Record the status and body as diagnostic evidence from the configured request path. The public contract does not guarantee the evaluation order between authentication, authorization, and job lookup, so a 404 is not by itself proof that the credential and Batch capability are valid. Handle 401 and 403 with the corrective actions below.

Avoid curl -v in shared terminals or logs: verbose request output includes the x-api-key header.

Send credentials

HTTP operations

Send x-api-key on every protected Batch REST or Realtime HTTP request:

curl -X POST "$API_URL/v1/transcribe/codeswitch?asr=bayan_cs_ar_en" \
  -H "x-api-key: $API_KEY" \
  -F "file=@meeting.wav"

Every currently published Batch REST and Realtime HTTP operation requires the x-api-key header.

Socket.IO connections

From a trusted Node.js or Bun runtime, send both headers during the Socket.IO handshake and use the provisioned path:

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: process.env.API_URL!,
  },
});

The released SDK clients configure this handshake from api_url and api_key; api_path is optional and defaults to /socket.io. They derive Origin from the configured api_url. Prefer them unless you need direct protocol control.

Resolve rejected credentials

Branch on the HTTP status first. Parse a machine-readable code when the response contains a structured platform error, and preserve an unstructured gateway or authentication response for diagnosis. Do not branch on message text.

Socket.IO can reject the connection or emit an error event, depending on when validation fails. Stop sending audio, check the same environment values and capability, then reconnect only after correcting the configuration.

Respond to an exposed or unused key

If a key appears in source control, client code, a URL, a log, or another untrusted location, treat it as exposed:

1. Stop using the key and remove it from active configuration and exposed locations. Deleting one visible copy does not make the key safe again.
2. Report the exposure through your organization's approved access flow without including the credential in the report, and follow the response instructions provided there.
3. If a replacement is issued, update the server-side secret and restart or redeploy every trusted runtime that used the old value.
4. Remove stale copies from secret stores and deployment configuration, then test a representative operation with the active configuration.

For an unused key, stop using it and follow the same approved access flow for the organization's retirement procedure.

Next steps

After the diagnostic produces the response expected for your configured environment, complete a first transcription with the SDK quickstart or review direct transport behavior.