API Credentials

Autoheal has two kinds of non-browser credential. Both are Authorization: Bearer tokens with no token exchange and no OAuth flow. Both resolve your organization, your identity and your permissions from the credential alone.

	Personal access token	Service account key
Belongs to	you	the organization
Permissions	exactly your current roles	the service account's roles
Created from	Your avatar menu → My tokens	Service accounts in your organization's sidebar, or a project's Settings → Service accounts
Prefix	ahpat_	ahsa_

Use a personal access token for ad-hoc work: your own scripts, your local CLI. Use a service account for automation: CI, scheduled jobs, config-as-code.

That distinction matters more than it looks. A personal access token deliberately carries your current access. If you lose a role, it stops working the same day. That is exactly what you want for a script you run yourself. It is exactly what you do not want for the deploy pipeline. Automation built on someone's personal token is only ever as durable as that person's access. A service account holds its own role, so it does not depend on any person's access.

Your first call

Every credential answers GET /api/v1/whoami. Make that call first. If it works, your credential is good, your organization is right, and you can see the roles you will be authorized against.

export AUTOHEAL_TOKEN='ahpat_...'
curl https://acme.autoheal.ai/api/v1/whoami \
  -H "Authorization: Bearer $AUTOHEAL_TOKEN"

{
  "actor_id": "sa_2f6a9c1e-4d3b-4a51-9f0e-8c2d1b7a5e42",
  "actor_type": "service_account",
  "actor_name": "deploy-bot",
  "tenant_id": "8b1f...",
  "roles": ["read_only"],
  "key": { "id": "7Kd3mZq9Xb2A", "name": "ci", "last_four": "k29P", "expires_at": "2026-11-01T00:00:00Z" }
}

Your organization is never a parameter, because Autoheal infers it from the credential. As a result, there is nothing to get wrong and no way to reach another organization's data.

Which endpoints accept a credential

There is no separate API for automation. A credential authenticates the same endpoints the Autoheal web app calls. You can open your browser's network tab, copy a request path, and use it with a token.

Reachable with a credential:

/api/v1/labels · /api/v1/alerts · /api/v1/incidents · /api/v1/catalog · /api/v1/oncall · /api/v1/integrations · /api/v1/integrationTypes · /api/v1/agent-profile · /api/v1/agent-policies · /api/v1/status-pages · /api/v1/skills · /api/v1/auth-settings · /api/v1/rbac · /api/v1/whoami · /api/investigations · /api/chat · /api/custom-agents · /api/instructions/runbooks · /api/instructions/agentsmd

Two paths inside those prefixes are the exception and require a browser session:

• /api/v1/integrations/tools/call (an internal endpoint the investigation agent calls, not a supported API)
• /api/v1/agent-profile/baseline (the platform-wide defaults, which are not yours to read or change)

Everything else requires a signed-in browser session. That includes organization administration, internal service endpoints, and, deliberately, credential management itself. You cannot mint or revoke a credential using a credential. This stops a leaked key from extending its own life or minting a more privileged sibling.

A path outside the list answers 401 with a JWT error rather than a credential error. That is the gateway saying "this path only accepts a browser session", not a problem with your token.

Personal access tokens

Your avatar menu → My tokens → New token. No permission is needed, and the tab is yours whatever your role.

Pick a name you will recognise later and an expiry: 30, 90, 180 or 365 days. The default is 90. Choosing No expiry requires typing the token's own name, so it is never the accidental option.

The secret is shown exactly once. It is stored as a SHA-256 hash, so nobody can recover it, including support and administrators. If you lose it, revoke it and create another.

Afterwards a token is identified by its name and last four characters. The list shows when each was created, when it expires, and when it was last used, so you can retire the ones nothing calls.

Revoking is immediate for you and takes effect everywhere within 60 seconds.

Your tokens are yours: no administrator can create one on your behalf or revoke one for you. An administrator can see that a token exists (name, owner, expiry, last use) through the organization-wide credential review, GET /api/v1/api-keys, but never its secret.

Service accounts

Service accounts in your organization's sidebar. Requires Org Admin. A service account can also live in one project, managed by that project's Project Admins from the project's Settings → Service accounts. See Managing Access.

1. Create the account, with its roles. Name it after the automation, not the person: deploy-bot, terraform, nightly-report. Pick the narrowest roles that work: a role on one project, such as Read-only for anything read-only. An organization account can be given roles on the organization or one project, or none yet.
2. Mint a key. The secret appears once, exactly like a personal token.

Change an account's roles later on IAM. A change takes effect on live keys within 60 seconds. There is no reissue: a key identifies the account, and the account's permissions are resolved on every request.

One account per automation

There are no per-key scopes, and that is deliberate. You can already express least privilege by creating a separate service account with a narrower role. That is the right granularity anyway, because it also gives each automation its own name in the audit trail and its own kill switch.

Limits, for the same reason: 25 service accounts per organization and 2 live keys per account. Two keys is a rotation overlap, not room to accumulate.

Rotation

Rotate rather than revoke-and-recreate when you are replacing a service-account key on a running system:

• A successor is issued immediately.
• The old key keeps working for a grace window (24 hours by default, 7 days at most).
• Callers switch to the new key whenever they restart, with no coordinated cutover.

If you believe a key has leaked, rotate with no grace. The old key stops working at once.

Personal access tokens cannot be rotated: rotation hands the new secret to whoever asked for it, and only you may ever hold yours. Revoke the old token and create a replacement.

Revoke is for killing a key outright: callers break immediately, and it cannot be undone.

Disable the account when you want to stop everything it does but keep the option to re-enable it. Every key is rejected within 60 seconds and recovers on re-enable, with no reissue. Delete is the irreversible version, and the account and all its keys go.

Expiry

Expiry is on by default: 90 days unless you choose otherwise. A finite expiry can be at most 365 days. No expiry is available only with the typed confirmation described above.

Whoever created a credential is emailed 14 days, 3 days and 1 day before it expires, and again on the day it does. Service-account pages also show a banner from 14 days out.

Nothing expires silently, but nothing is renewed automatically either, so rotate before the date or the calls start failing.

Attribution

Anything a credential does is attributed to it. An investigation started by a service account shows "deploy-bot (service account)" in its timeline, and you can filter investigation and chat lists by that actor. A personal access token's actions are attributed to you, because they are yours.

Every create, rotation, revocation and disable is recorded with who did it and when, on the service account's Audit tab. Failed authentication attempts against a real key are recorded too, so a credential being probed is visible.

Permissions

A credential can never do more than its actor's role allows. The full matrix is in Roles & Permissions. The credential-specific permissions are:

Permission	Org Admin	Project Admin	Member	Read-only
Manage your own personal access tokens	yes	yes	yes	yes
See service accounts in a project's settings		yes	yes	yes
Create, rename, disable and delete the organization's service accounts. Create, rotate and revoke their keys	yes
Create, rename, disable and delete a project's service accounts. Create, rotate and revoke their keys		yes
Review every credential in the organization	yes

Org Admins see every service account, project ones included, in your organization's Service accounts.

Managing your own tokens needs no permission at all: a token carries your access and nothing more, so creating one is not an escalation.

Setting a service account's roles needs permission to manage access where the role is given: on the organization, or on the project.

Rate limits

Limit	Value
Per credential	60 requests / minute
Per organization	600 requests / minute

Exceeding either returns 429 with a Retry-After header. Wait that many seconds, then retry.

Errors

Status	Meaning
401	The credential is missing, malformed, unknown, expired, revoked, belongs to a disabled service account, or belongs to a deactivated user.
403	The credential is valid but its role lacks the permission. The response names the permission you need.
429	Rate limited. See Retry-After.

Every 401 returns the same body, on purpose. An attacker probing for valid credentials must not be able to tell "no such key" from "wrong secret" from "expired". If your own credential is failing and you cannot tell why, an administrator can see the reason in the credential audit trail. The administrator never sees the secret.

Security

• Nothing is recoverable. Only SHA-256(secret) is stored. A lost secret is replaced, not recovered.
• Revocation is bounded at 60 seconds. It is immediate on the server handling the request and propagates within a minute.
• Leaked keys are detectable. Both prefixes carry a checksum, so secret scanners can recognise a credential in a commit or a log.
• Never put a credential in a URL. Query parameters appear in browser history, proxy logs and referrer headers. Use the Authorization header, over HTTPS only.
• Store it in your CI's secret store, not in a repository, not in an environment file you commit.
• Review periodically. GET /api/v1/api-keys lists every live credential in the organization, service-account keys and personal-token metadata alike, with its last use. This is the fastest way to find one nobody calls any more. Like all credential management, it needs a signed-in admin session, not a credential.

Turning credentials off

API keys and service accounts (support-managed) is the master switch. With it off, nobody can manage credentials, but credentials that already exist keep working, so disabling it never strands automation mid-request. Revoke a credential to stop it. Personal access tokens are always available to everyone in the organization. Revoke one to stop it.