Get started

Get and use a HeyRik API key

Create your HeyRik API key, store it safely, authenticate your first request, and resolve common access errors.

8 minute read Practical examples included

A HeyRik API key authenticates your server to the HeyRik API. It is scoped to the account that created it, so requests only access that account's agents, phone numbers, calls, campaigns, and balance.

Treat the key like a password

Keep it on your server. Never place it in browser code, a mobile application, screenshots, public repositories, or support messages.

Create a HeyRik API key

Create the key from your HeyRik dashboard before making API requests.

Sign in to HeyRik

Open the HeyRik dashboard with the account that owns the agents and calls you want to manage.

Open API keys

Go to the API section and choose API keys.

Create a key

Give the key a recognizable name for the environment or service using it.

Copy it once

Save the generated key immediately in your secure environment configuration.

Open API keys

Store the key safely

Use an environment variable so the key stays separate from application code.

.env.local

HEYRIK_API_KEY=cg_live_xxxxxxxxxxxx

Use in Node.js

const apiKey = process.env.HEYRIK_API_KEY;

if (!apiKey) {
  throw new Error("HEYRIK_API_KEY is not configured");
}

Keep environment files private

Add local environment files to .gitignore. In production, use the encrypted secret or environment-variable system provided by your hosting platform.

Authenticate a request

HeyRik accepts either a Bearer token or the X-API-Key header. Choose one approach and use it consistently.

Bearer authentication

curl https://server.heyrik.com/api/v1/agents \
  -H "Authorization: Bearer $HEYRIK_API_KEY"

X-API-Key authentication

curl https://server.heyrik.com/api/v1/agents \
  -H "X-API-Key: $HEYRIK_API_KEY"

Node.js fetch

const response = await fetch("https://server.heyrik.com/api/v1/agents", {
  headers: {
    Authorization: `Bearer ${process.env.HEYRIK_API_KEY}`,
  },
});

if (!response.ok) {
  throw new Error(`HeyRik API error: ${response.status}`);
}

const { data: agents } = await response.json();

Test the API key

List agents to confirm that the key is valid and connected to the expected account.

Test request

curl https://server.heyrik.com/api/v1/agents \
  -H "Authorization: Bearer $HEYRIK_API_KEY"

Successful response

{
  "data": [
    {
      "id": "agc_9f2a1c30",
      "name": "Support Agent",
      "language": "en-IN",
      "created_at": "2026-07-24T06:11:44.201Z"
    }
  ]
}

API key check

authenticated

HTTP status200 OK

Account accessConfirmed

Agents returned1

Next stepCreate or configure an agent

Resolve authentication errors

Use the HTTP status and error code to find the likely cause.

401missing_api_key

Add Authorization: Bearer … or X-API-Key to the request.

401invalid_api_key

Check for missing characters, extra spaces, or a key that was replaced.

403forbidden

The key is valid but the requested action is not allowed for this account.

404not_found

The resource may belong to another account. Keys only see their own account’s data.

429rate_limited

Slow down requests and retry with backoff.

API-key security checklist

Complete these checks before using the key in production.

01The key is stored in an encrypted secret or environment-variable system.02Browser and mobile code never receive the key.03Local environment files are ignored by Git.04Development and production use different keys.05Logs and error reports redact authorization headers.06A compromised or unused key is replaced immediately.07Only the backend service that needs HeyRik access can read the key.

Need help with your HeyRik API key?

Email info@heyrik.com and describe the error code. Never include the key itself.