Skip to content
Echopoint Echopoint Docs

API keys & permissions

API keys are how automation — CI pipelines, scripts, integrations — authenticates against the Echopoint API. Manage them under API Keys in the app.

How keys work

Section titled “How keys work”
  • Org-scoped — a key belongs to one organization and only reaches that organization’s webhooks, flows, and collections.
  • Scoped permissions — each key carries an explicit list of scopes; requests outside those scopes are rejected.
  • Shown once — the secret is displayed a single time at creation. Copy it into your secret store immediately; it cannot be retrieved later.
  • Expiration — keys support an expiration date, so short-lived credentials are the default posture rather than an afterthought.
  • Auditable — create, audit, and rotate keys from the same screen.

Keys are sent as headers on API requests:

Terminal window
curl https://api.echopoint.dev/flows \
  -H "X-Api-Key: $ECHOPOINT_API_KEY" \
  -H "X-Organization-Id: $ECHOPOINT_ORGANIZATION_ID"

The CLI reads the same pair from ECHOPOINT_API_KEY and ECHOPOINT_ORGANIZATION_ID; the GitHub Action takes them as the api-key and organization-id inputs.

Scopes

Section titled “Scopes”

Scopes follow a resource:action shape. Examples from the catalog:

ScopeGrants
flows:readList and read flows (needed to resolve tag selections)
flows:executeLaunch flow executions
webhooks:readRead webhook endpoints and captured requests
runner:completeRunner protocol permission; not needed on current CLI ephemeral-run keys

The full catalog is served by the API at GET /permissions — see the API reference.

The ci preset

Section titled “The ci preset”

The app offers a ci preset. Review the selected scopes and use the minimum required for your pipeline: current CLI ephemeral runs need flows:execute, plus flows:read for tag selection. They report results using a per-job token.

Scopes by use case

Section titled “Scopes by use case”
Use caseScopes
CI runs by flow IDflows:execute
CI runs by tag (--tag / tags:)flows:execute + flows:read
Read-only flow inventory (dashboards, scripts)flows:read
Reading captured webhook requestswebhooks:read

Grant the minimum set: a key that only launches pinned flow IDs does not need flows:read, and a reporting script needs no execute scope at all.

Rotation

Section titled “Rotation”
  1. Create a replacement key with the minimum required scopes and an expiration date.
  2. Update the secret wherever it is consumed — CI secret stores, ECHOPOINT_API_KEY env vars, the GitHub secrets.ECHOPOINT_API_KEY value.
  3. Confirm a run succeeds with the new key, then delete the old one.

Expirations make rotation routine: set one on every key so a forgotten credential ages out instead of living forever. The GitHub Action masks the key in logs automatically. An ephemeral execution claim delivers resolved inputs, including referenced secrets, to the worker. Protect that worker and grant execute permission only to callers you trust with those inputs.

Next steps

Section titled “Next steps”