# Authentication

> Create an API key, send it as a bearer token, and keep it out of your client code.

Source: https://www.hey.support/docs/api/authentication

---

The API authenticates with a workspace API key sent as a bearer token.

## Create a key

Go to **Settings → Developer** and create a key. You must be the workspace **owner**, and the workspace must be on **Scale or above**.

A key looks like:

```
hs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

<Callout type="warn">
  The key is shown **once**, at creation. We store only a hash of it, so we cannot show it to you again — copy it then. If you lose it, revoke it and create another.
</Callout>

## Send it

Pass it in the `Authorization` header on every request:

```bash
curl https://www.hey.support/api/v1/me \
  -H 'Authorization: Bearer hs_live_…'
```

`GET /me` is the cheapest way to check a key works — it returns the workspace the key belongs to.

## Scope

A key is scoped to the **workspace** that created it, not to a single agent. It can read and write every resource in that workspace, so treat it as a full credential.

Requests for resources in any other workspace return `404`.

## Rate limits

Limits are per key, per hour. Once a key is accepted, every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` — successes included, not only the request that gets refused — so you can pace a job instead of waiting to be told no. Read `Remaining` as you go rather than counting requests yourself. (A rejected key returns `401` with no rate headers, since there is no key to report on.)

Going over returns `429`. See [Errors](/docs/api/errors) for the ceiling and the retry advice.

## Keep it server-side

An API key is a secret. Never ship one in browser JavaScript, a mobile app, or anything else a user can read — anyone holding it has your workspace's data.

If you need to put the chat widget on a page, that is the [embed script](/docs/build/embed-script), which needs no key at all.

## Revoking

Revoke a key from **Settings → Developer**. Revocation takes effect immediately, and any request using it then gets a `401`.

Revoke and replace if a key is ever pasted into a shared document, a ticket, a log, or a repository.

## If your plan changes

API access is a **Scale** feature. Dropping below Scale does not delete your keys, but requests start returning `403` — including any [Zapier](/docs/integrations/zapier) automations, which run on this same API. Upgrading restores them without you re-creating anything.