> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/developer-reference/api/managing-api-keys.md).

# Managing API Keys

API keys authenticate external systems that call the [Alhena REST API](/docs/developer-reference/api.md) and the [end-user MCP server](/docs/features/mcp.md). You can create and manage them directly from the dashboard under **Settings > API Keys**.

{% hint style="warning" %}
**API keys must be enabled for your account by Alhena support.** If you don't see **Settings > API Keys** — or the page reads *"API keys are not available for this account."* — contact Alhena support to have it enabled.
{% endhint %}

{% hint style="info" %}
Only **organization admins** can view and manage API keys. Other team members see *"Only organization admins can manage API keys."*
{% endhint %}

## Creating a key

1. Go to **Settings > API Keys** and click **Create new key**.
2. If your organization has more than one bot profile, select the **Bot profile** the key should act on behalf of. (With a single profile, it's selected automatically.)
3. Optionally enter a **Label** to identify the key later, e.g. *"Backend integration"* or *"Read-only MCP"*.
4. Choose the **Scopes** that control which endpoints the key can call (see below). A new key defaults to **All access** — toggle that off to restrict it.
5. Click **Create key**.

{% hint style="danger" %}
**Copy the key immediately — you won't see it again.** For security, Alhena shows the full key only once, at creation. If you lose it, revoke the key and create a new one.
{% endhint %}

After creation, the list shows only a masked version of each key (e.g. `••••••••abc123`).

## Scopes

Scopes limit which endpoints a key can call. A key authenticates against an endpoint only if its scopes include that endpoint's required scope. Selecting **All access** grants every scope (current and future) and disables the individual toggles.

| Scope            | Grants access to                                                                                                                 |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **All access**   | All Developer API endpoints.                                                                                                     |
| **Send Message** | `POST /api/v1/send_message` — send a query to the AI and receive a response.                                                     |
| **AI Search**    | `POST /api/v1/search` — AI-powered product search over your catalog.                                                             |
| **Product FAQs** | `GET /api/v1/product-faqs` — fetch generated FAQs for a page.                                                                    |
| **Agent Assist** | Agent-assist endpoints used by the Zendesk and Freshchat apps.                                                                   |
| **MCP Server**   | `POST /api/mcp/` — access the end-user Model Context Protocol server. Grants access to **all bot profiles** in the organization. |

## Managing existing keys

The **API Keys** table lists each key with its name, masked value, associated bot profile, scopes, and creation date.

* **Edit** — update a key's label and scopes. The key value itself and its bot profile can't be changed; create a new key if you need a different value or profile. At least one scope must remain selected.
* **Revoke** — permanently disable a key. Revoking takes effect **immediately** and **cannot be undone** — the key stops working as soon as you confirm. To rotate a key, revoke the old one and create a replacement.

## Using a key

Pass the key as a Bearer token in the `Authorization` header:

```shell
curl https://api.alhena.ai/api/v1/send_message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ALHENA_API_KEY" \
  -d '{ "query_text": "Hi" }'
```

If a key is missing the scope an endpoint requires, the API responds with `403` and `{"status": "error", "message": "Missing scope: <scope>"}`.

## Related Pages

* [REST API](/docs/developer-reference/api.md) — Endpoint reference for the Developer API
* [AI Assistants (MCP)](/docs/features/mcp.md) — The end-user MCP server reached with the **MCP Server** scope
* [Website SDK](/docs/developer-reference/website-sdk/javascript-api.md) — Frontend integration that does **not** require an API key