API Credentials

Inference API and machine install keys: what each is for, and how to create, rotate, and revoke them

User > Keys creates two types of ac_ credential. They look alike but grant different access, and neither can do the other's job.

Key typeUsed forCan't do
Inference APICalling the public API at api.actual.inc from your applications, scripts, and tools such as Hermes.Install or register computers.
Machine install (fleet)Installing Actual and registering any number of computers to your account, for example across a fleet.Call the inference API.

Chat uses your web session and needs neither. Machine install keys are rolling out gradually; if User > Keys has no Key type selector, your account only has Inference API keys for now.

Create and copy

  1. Open User > Keys.
  2. If a Key type selector is shown, leave it on Inference API. Optionally enter a name for the credential.
  3. Choose add.
  4. Copy the full secret from the creation view and store it securely.
  5. Choose done after saving it.

The full secret is available only in that creation view. After done, the list shows a safe preview rather than a recoverable secret.

Use the credential

Set ACTUAL_API_KEY in your application's environment and send it as a bearer token:

Authorization: Bearer ac_your_credential_here

The public API supports model inventory and inference. Downloading and loading models uses the CLI or website, not a public model-management endpoint. See API Quickstart and API Reference.

Machine install keys for fleets

The command on the Add Computer screen is single-use: it expires after 10 minutes and works for one computer. A machine install key is reusable, so one key can enroll many computers from a script or a configuration management tool.

  1. Open User > Keys and set Key type to Machine install (fleet).
  2. Choose the release Channel. Stable is always available; beta and nightly appear only for accounts that have access.
  3. Optionally enter a name, choose add, and copy what you need before choosing done:
    • macOS / Linux and Windows are install commands with the key embedded. Run one on each computer.
    • Already installed is actual login <key>, which registers a computer that already has Actual.

Every computer enrolled with the key is registered to the account that created it. Machine install keys don't expire and have no use limit. Treat one like a password, because anyone who holds it can add computers to your account. Terminate it when the rollout is done.

Terminate or rotate

Terminate works the same way for both key types. Select an existing credential in the Keys list, choose Terminate, and confirm with Destroy. Keep cancels that confirmation. A destroyed credential cannot be restored.

For rotation, create and test a replacement, update the applications that use it, then terminate the old credential. A missing, invalid, or revoked credential produces an authentication failure; retrying with the same secret does not fix it.

Never commit credentials to source control or paste them into shared logs. Store them in environment variables or a secrets manager.