# Get and use a HeyRik API key

> Get a HeyRik API key, authenticate requests with Bearer or X-API-Key headers, test the key safely, understand permissions, and troubleshoot authentication errors.

Source: https://www.heyrik.com/docs/guides/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](https://www.heyrik.com/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 status**200 OK**

Account access**Confirmed**

Agents returned**1**

Next step**Create or configure an agent**

## Resolve authentication errors

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

401`missing_api_key`

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

401`invalid_api_key`

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

403`forbidden`

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

404`not_found`

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

429`rate_limited`

Slow down requests and retry with backoff.

## API-key security checklist

Complete these checks before using the key in production.

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

**Need help with your HeyRik API key?**

Email [info@heyrik.com](mailto:info@heyrik.com) and describe the error code. Never include the key itself.