API Tokens
Programmatic bearer tokens that connect your application to PromptHelm.
API tokens are organization-scoped bearer credentials that authorize SDK and REST traffic to the PromptHelm gateway. They live next to (but are distinct from) the short-lived JWTs the dashboard uses — tokens never expire on their own, but you can revoke them instantly.
Format
phk_3a9f1b2c4d5e6f70819ad7e8f9c0b1a2Every token is the literal prefix phk_ followed by 32 hex characters
(36 characters total, lowercase). The prefix makes leaks easy to spot
in logs and grep.
Scopes
The v1 schema ships with a single scope:
| Name | Type | Default | Description |
|---|---|---|---|
| gateway:execute* | scope | — | Permits POST /api/v1/gateway/execute and /stream calls against any prompt in the issuing organization. |
Future scopes (prompts:write, analytics:read, audit:read) will be
opt-in per token; existing tokens stay limited to gateway:execute.
Reveal once
The plaintext token is shown exactly once, at creation time. PromptHelm stores only an HMAC-SHA256 hash — there is no recovery flow and no support back-door.
Treat tokens like passwords
Never commit a token to source control. Never paste one into a chat channel or screenshot. Use your platform's secret manager (GitHub Actions secrets, Vercel env vars, AWS Secrets Manager, Doppler).
Revoking
Revocation is instantaneous. The dashboard's Revoke action drops
the token from the cache layer (Redis) and the next request from the
revoked token returns 401 unauthorized. The token's hash and metadata
remain in the audit log.
Tier limits
| Name | Type | Default | Description |
|---|---|---|---|
| Free | limit | — | Up to 2 active tokens per organization. |
| Pro | limit | — | Up to 20 active tokens per organization. |
| Business / Enterprise | limit | — | Unlimited active tokens. |
Rotation
Best practice is to rotate every token annually, and immediately if you suspect a leak. The rotation flow:
Create a new token with the same name plus a date suffix, e.g.
ci-prod-2026-05. Copy the value into your secret manager.Deploy the new value to your application. PromptHelm allows multiple active tokens per organization, so the cutover can overlap.
Once the dashboard's analytics show zero traffic on the old token, revoke it. The audit log preserves the trail.
Calling the gateway
curl -X POST https://api.prompthelm.app/api/v1/gateway/execute \
-H "Authorization: Bearer $PROMPTHELM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"promptSlug":"support-triage","variables":{"ticket":"..."}}'The SDKs read PROMPTHELM_API_KEY from the environment by default —
see the Node.js or
Python quickstarts for the full setup.