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:completePublish execution results back (ephemeral and self-hosted runners)

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

The ci preset

Section titled “The ci preset”

When creating a key, the curated ci preset selects the scopes a pipeline needs in one click — including flows:execute and runner:complete. Prefer it over hand-picking scopes for CI keys.

Scopes by use case

Section titled “Scopes by use case”
Use caseScopes
CI runs by flow IDflows:execute + runner:complete
CI runs by tag (--tag / tags:)flows:execute + runner:complete + 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 same scopes (use the ci preset again for pipeline keys) 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, and resolved environment values are never logged.

Next steps

Section titled “Next steps”