Looking for the full interactive reference?

Open API Reference →

Apps

Builder lifecycle end-to-end: create an app in the console, declare scopes, attach a listing, submit, install on your test org, debug, revoke.

Builder actions live in the console

All create/activate/update/revoke actions happen inside the GA Flight console at Settings → Developers → Apps. This page is the conceptual companion — it does not replace the in-product flow.

What is a developer app

A developer app is the unit of identity for any integration you publish on the GA Flight platform. It is owned by exactly one organization (the builder org), declares the maximum scope set any of its listings may request, and is the parent record that mints API keys and signs webhook deliveries. One app may back many addon listings; each install of any of its listings auto-provisions its own (api_key, webhook_endpoint) pair under the app.

Status states

Apps have three lifecycle states. Transitions are linear and irreversible — revoke is a one-way door.

StateStabilityMeaning
draftstableNewly created. The app exists but cannot mint credentials or back a published listing.
activestableActivated by the builder. Can mint API keys, declare scopes, and back addon listings.
revokedstablePermanently disabled. All downstream credentials and installs cascade-revoke. Cannot be un-revoked.

Transition diagram:

bash
┌────────┐  activate   ┌────────┐   revoke    ┌─────────┐
│ draft  │ ──────────▶ │ active │ ──────────▶ │ revoked │
└────────┘             └────────┘             └─────────┘
                            │
                            │  update scopes / metadata
                            │  (stays in active)
                            └─────▶ active

Per-org ownership

Every developer app is owned by exactly one organization via developer_apps.owner_org_id. Only members of the owner org with the developer.app:manage permission can create, update, or revoke the app. Listings, installs, and credentials downstream of the app all inherit this tenancy boundary.

Scope declaration

Scopes declared on the developer app form the maximum set any addon listing backed by this app may request. Listings inherit this constraint; a listing that requests a scope outside the app's declared set will fail the automated submit check. See the scope catalog for the 13 read scopes available at v2.1, and review policy for the per-scope justification rule.

Activation

Activating an app flips developer_apps.status from draft to active and opens up API key minting. The first key the console reveals is the only chance to capture the plaintext token — only a SHA-256 hash is stored on the server. Send the bearer header and X-Org-Id on every request.

First authenticated call with an app-minted API key:

bash
curl https://api.gaflight.io/api/v1/public/pilots \
  -H "Authorization: Bearer gaf_pk_<your-app-key>" \
  -H "X-Org-Id: <your-org-uuid>"

Revoke + 4-layer cascade

Revoking a developer app is permanent and triggers a 4-layer cascade. Every credential and install downstream of the app is force-revoked in the same transaction, with audit rows written for each state transition. Use it when an app is compromised or sunset.

Cascade order:

bash
developer_app.status = 'revoked'
   │
   ├─▶ api_keys.status = 'revoked'           (all keys minted by this app)
   │
   ├─▶ addon_listings.status = 'deprecated'  (all listings backed by this app)
   │
   ├─▶ app_installations.status = 'uninstalled'
   │       (all installs of all listings backed by this app)
   │
   └─▶ webhook_endpoints.disabled_reason = 'install_revoked'
           (every endpoint auto-provisioned by an install of those listings)

Irreversible

There is no un-revoke action. To resume integration work after a revoke, create a new developer app, re-declare scopes, and publish a fresh listing. Consumers will see the prior listing transition to deprecated and lose API access immediately.

Debug

Webhook delivery logs are available in the console at Settings → Integrations → Event log. Each delivery surfaces its signature, response status, and retry trail. Replay a single delivery via the API (see Webhooks → Replay) or from the event log UI. The catalog of emitted event types lives at Events.