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

> ## Agent Instructions
> Treat availability labels as authoritative. Do not present planned surfaces as live.
> The product MCP can act on Actual Jobs; the documentation MCP cannot.

# Authentication and idempotency

> Prepare secure, repeat-safe requests for the planned Actual API.

<Warning>API credentials and the public API are planned and are not currently issued.</Warning>

## Authentication

The planned HTTP API uses bearer credentials over HTTPS.

```http theme={null}
Authorization: Bearer $ACTUAL_API_KEY
```

Keep credentials in a server-side secret manager. Do not embed them in browser bundles, mobile applications, prompts, model context, logs, URLs, or source control. Authentication does not grant access to every Account object and does not constitute Approval.

## Idempotency

Every mutation will require or use an `Idempotency-Key`.

```http theme={null}
Idempotency-Key: checkout-order-4821-create-job
```

Choose a stable key for one semantic intent. A retry of the same intent uses the same key; a changed intent uses a new key. Reusing a key with a different body should be treated as an error.

Idempotency prevents duplicate command processing. It does not make an ambiguous external effect safe to repeat. If Actual reports that an action outcome is unknown, wait for reconciliation rather than submitting a replacement action.

## Safe retry outline

1. Retry reads only for transient failures and with bounded backoff.
2. Retry a mutation only with its original idempotency key.
3. Honor `Retry-After` on rate limits.
4. Refresh state on revision or Approval conflicts.
5. Never blind-retry an ambiguous external action.