Introduction

Getting your API key

Learn how to obtain your API keys and understand the supported authentication strategies for securely accessing Hume APIs.

API keys

Each Hume account is provisioned with an API key and Secret key. These keys are accessible from the Hume Portal.

Follow the steps below to access your API keys:

  1. Sign in: Visit the Hume Portal and log in, or create an account.
  2. View your API key: Navigate to the API Keys page to see your key.
API key view within the Hume portal

Your API key, used for API key authentication, is a random sequence of letters and numbers that is 48 characters long.

Your Secret key, used in generating a Client ID for token authentication, is another random, alphanumeric sequence that is 64 characters long.

Authentication strategies

Hume APIs support two authentication strategies:

  1. API key strategy: Designed for server-side development, this strategy allows developers to make an authenticated request to Hume APIs with their API key.

All Hume APIs support this authentication strategy.

  1. Token strategy: Tailored for client-side development, this strategy involves an additional API call to obtain the Access Token. This adds a layer of security, ensuring the API key does not get exposed.

Today, only our Empathic Voice Interface (EVI) supports this authentication strategy.

The sections below explain how to use each of the supported authentication strategies.

API key authentication

API keys can be used to authenticate calls to Hume’s APIs, either through REST API endpoints or with a WebSocket.

For REST API endpoints, include the API key as a request header.

$curl https://api.hume.ai/v0/evi/{path} \
>  --header 'Accept: application/json; charset=utf-8' \
>  --header "X-Hume-Api-Key: <YOUR API KEY>"

For WebSocket endpoints, include the API key as a query parameter in the URL.

1const ws = new WebSocket(`wss://api.hume.ai/v0/evi/chat?api_key=${apiKey}`);

Token authentication

While API key authentication only requires an API key, token authentication requires both an API key and a Secret key. Together, they are used to generate a Client ID, which is required to fetch an Access Token.

See the steps below for how to generate a Client ID and fetch an Access Token:

  1. Generate a Client ID: Concatenate your API key and Secret key, separated by a colon (:), then base64 encode the string to produce your Client ID.

  2. Fetch Access Token: Initiate a POST request to https://api.hume.ai/oauth2-cc/token with the Client ID included in the request headers.

cURL
1# API keys sourced from .env variables or secure store
2apiKey="${API_KEY}"
3secretKey="${SECRET_KEY}"
4# Append API key and Secret key, separated by a colon
5authString="$apiKey:$secretKey"
6# Base64 encode auth string
7clientId=$(echo -n "$authString" | base64)
8# Perform the API request
9response=$(curl -s --location 'https://api.hume.ai/oauth2-cc/token' \
10  --header 'Content-Type: application/x-www-form-urlencoded' \
11  --header "Authorization: Basic $clientId" \
12  --data-urlencode 'grant_type=client_credentials')

To make an authenticated request with your Access Token, include it as a query parameter in the request URL.

EVI
1const ws = new WebSocket(`wss://api.hume.ai/v0/evi/chat?access_token=${accessToken}`);