> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> A scoped secret that lets an external system call the Alforse API on your behalf, with its own permissions.

An API key authenticates programmatic requests to Alforse. Each key belongs to one company and has explicit permission scopes. A request can do only what the key's scopes and its creator's current permissions both allow. Manage keys under **Settings → API Keys**.

TIP

**Connectors don't need a key**

Claude.ai, Claude Desktop, and ChatGPT connect over **OAuth**. The connection inherits the authorizing user's role and company. Use an API key for clients without browser-based OAuth, including Claude Code, Cursor, VS Code, Codex, headless scripts, and CI. Stdio-only clients connect through `mcp-remote`. See Authentication for both flows.

## Creating a key

Alforse screenshot**Settings → API Keys: the key list with masked previews, scopes, and rate limit, plus the one-time 'You can only see this key once' dialog**

The full key is shown exactly once at creation.

Select **New API Key**, enter a company-unique **Name**, optionally set **Expires At**, grant scopes, and save. A blank expiration means the key does not expire. Alforse displays the full key once and then stores only its SHA-256 hash and a five-character preview. Copy the key immediately; if it is lost, delete it and create another. The dialog also provides an MCP connection command.

HEADS UP

**The key is a bearer secret**

Anyone holding the key can act as it, within its scopes. Store it in a secret manager, never commit it, and rotate (delete and recreate) if it leaks.

## Authenticating a request

Send an Alforse API key as a bearer token. The service-layer API uses `POST /api/v1/{module}/{operation}`; the public API host is `https://api.alforse.com`.

```http theme={null}
POST /api/v1/{module}/{operation}
Host: api.alforse.com
Authorization: Bearer alf_your_key_here
Content-Type: application/json
```

API keys require no login or refresh flow. Alforse hashes each submitted key and checks its record, expiration, and rate limit before processing the request.

NOTE

**Bearer at the edge, alforse-key underneath**

The service-layer API accepts `Authorization: Bearer alf_…`; `alforse-key` is also accepted as a compatibility header. API v1 requires an `alf_` API key. OAuth connectors use the MCP endpoint.

## Scopes and rate limit

A key has only its stored `module_action` scopes, such as `sales_view` or `inventory_create`, limited to what its creator can currently do, and can access only its company. A key with no scopes can authenticate but cannot read or write data. Scope changes and deletion take effect immediately. API access requires the **Business** or **Partner** plan (feature `API_KEYS`); requests from a Starter-plan company return `403` regardless of scope.

New keys allow **60 requests per minute** (window `1m`; a platform policy can also use `1h` or `1d` windows). Each key's limit is shown in the **Rate Limit** column and counted per key. You cannot change it in the app; if an integration needs more, contact Alforse support. A rejected request returns `429` (`Rate limit exceeded`) with `Retry-After` and `X-RateLimit-*` headers; retry after the specified interval.

## What the key unlocks

Use the **Alforse API** by default. It validates input, updates derived data, and enforces permissions through Alforse's service layer. Each operation accepts the same arguments over HTTP at `POST /api/v1/{module}/{operation}` and through MCP. Operations are classified as `READ`, `WRITE`, or `DESTRUCTIVE` so clients can gate them by risk. The reference includes examples and an OpenAPI specification for generating client SDKs.

The **Data API** provides direct REST access to tables and views under the app's row-level security policies.

HEADS UP

**The Data API is outside the service layer**

Data API writes bypass the service layer and do not recalculate derived values such as totals, statuses, or ledger entries. Use direct writes only when the Alforse API does not expose the required operation and you understand all affected data.

## Keys versus webhooks

An **API key** authorizes requests to Alforse. A **[webhook](/docs/building/webhooks.md)** notifies your service when a subscribed record changes. They are independent: a webhook is signed with its own signing secret, never with an API key. A typical integration uses the webhook as a change notification, then fetches the current record with an API key.

**Webhooks**

Get an HTTP callback when an Alforse record changes, then pull the detail with your key.

[Open](/docs/building/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.