Skip to content
StackHeal

API

Authentication

API tokens, scopes and rotation.

The StackHeal REST API authenticates with bearer tokens. A token is bound to a tenant scope and a role, so an API caller has exactly the permissions a user with that role would have — no more.

Scopes

Tokens carry scopes that map to the role model: triggering runs, reading run history, managing workflow definitions, and administrative operations. Issue the narrowest scope the integration needs; a system that only triggers runs should not hold a token that can edit definitions.

curl https://api.stackheal.example/v1/runs \
  -H "Authorization: Bearer $STACKHEAL_TOKEN" \
  -H "Content-Type: application/json"

Keep tokens server-side

API tokens belong in a secret manager and in server-side code. They must never be embedded in a browser bundle, a mobile app, or a repository.

Rotation

Tokens can be rotated with an overlap period so a caller can move to a new token before the old one is revoked. Revocation takes effect immediately.

Scope of this documentation

This page describes how the StackHeal platform is designed to behave. This website does not execute workflows or connect to infrastructure — see the repository README for the backend integration points.