API keys

An API key is how a system outside Perstack authenticates to the API — starting a run, reading a record, resolving an approval, without a person in the loop. This page covers issuing keys, scoping them, and rotating them out.

Issuing a key

Create a key from Studio under organization settings, or with POST /api/v1/api-keys. Give it a name that says what it is for — the system or integration that will use it — since that is what you will see later when deciding whether it is still needed.

Set expiresIn to a number of seconds between 60 and 31536000, or set expiresAt to an explicit timestamp. Omit both, or use expiresAt: null, for no expiry. The new key's lifetime is independent of the key used to create it.

Key creation requires api-keys:create, whether you use Studio or an API key. A key with that permission can create a key with different operations and resource targets; the calling key's grants are not an upper limit on the new key.

Scoping

A key can be scoped to a specific set of operations rather than everything your account can reach. A key used only to submit new invoices for processing does not need the ability to approve payments or read unrelated records, so it should not carry that access.

Supply a grants object with organizationOperations, projectGrants, agentGrants, and optional environmentGrants. At least one grant must be nonempty. Target resources must belong to the authenticated Organization, and Agent and Environment IDs must match their stated Project. An Environment can receive grants while provisioning. These checks do not compare the requested grants with the calling key's grants.

When the new key is used, its own grants and the user's current resource permissions authorize that request. Creating a key does not grant its user a new Organization or Project role. See Operations and rules.

Revoking

Revoking a key takes effect immediately — any request authenticated with it after that point is refused. Revoke a key as soon as the system using it is decommissioned or the integration is no longer needed, rather than leaving unused keys active.

Rotating

If a key has an expiry, replace it before that date to avoid interrupting the consumer.

There is also no in-place way to change what an existing key's secret value is. Rotating means creating a replacement key — with the same or adjusted scope and the intended expiry — updating the system that uses it to the new key, and then revoking the old one. Keeping both active briefly during the switch avoids a gap where the calling system has no working credential. Plan rotations around the expiry you set, rather than waiting for a key to fail.

To manage who on your team can issue keys in the first place, see Organization.