Use the API

Everything the console does, the API does. The console itself is a client of it. For a terminal or coding agent, start with the CLI, which handles protected state, browser handoffs and creation retries. Direct integrations can use the same API from a deployment script or CI job.

Management keys

A management key authenticates API calls to the /v1/admin/* routes. Open the user menu in the console, choose Management keys, and click New key. The key is shown once in a dialog titled Copy your new key now.

A management key acts within its owning identity's current account membership and role. It does not expire. Store it in a secret manager and read it from the environment. Revoke key stops it immediately.

Keys are created, listed and revoked from the console only. A management key cannot do any of the three, so a key you hand to another system cannot issue itself a second key, and revoking the one you handed out ends that access for good.

Management keys manage; they never call providers. An app's own API key is what calls providers, and a management key is refused on those routes.

Making a call

Send the management credential as an Authorization: Bearer header from your HTTP client's protected credential store. Do not put it in shell arguments or logs. The CLI can read an existing key through stdin:

agw deployment connect --url https://api.appaigateway.com --key-stdin < /private/path/management-key
agw app list --json

The full reference with every request and response shape is under API reference, and the OpenAPI document is at /openapi.json.

What you can do

Validate before you write

POST /v1/admin/apps/{app}/validate checks an application body without saving it and returns the same errors a write would. Run it before PUT in any automated flow, so a bad configuration is caught before it replaces a good one.

Rules worth knowing

• Never send id when creating an app. The gateway assigns it and returns it as app.id. A body with id is refused with 400.
• PUT /v1/admin/apps/{app} replaces the whole app: send name, the full config and optionally status. Fetch first, change, then put.
• An app's API key is returned once, as api_key.key on create or key on POST …/keys. Nothing returns it again.
• A provider key is never returned. Responses carry only secretHint, the last characters.
• Every write takes up to a minute to apply everywhere.

Example: create a server app and its first key

curl --fail-with-body "$GATEWAY_URL/v1/admin/apps" \
  -H "Authorization: Bearer $APP_AI_GATEWAY_MGMT_KEY" \
  -H 'Content-Type: application/json' \
  -d @- <<'JSON'
{
  "name": "Search service",
  "config": {
    "authentication": { "type": "api_key" },
    "routing": {
      "providers": {
        "mode": "selected",
        "selected": { "openai": { "allowed_paths": ["v1/responses"], "allowed_models": ["gpt-5.6"] } }
      },
      "model_rewrites": {}
    },
    "limits": {
      "per_user": { "requests": { "per_minute": null, "per_day": null }, "spending": { "monthly_usd": null } },
      "per_app": { "requests": { "per_minute": 300, "per_day": 10000 }, "spending": { "monthly_usd": 100 } }
    }
  }
}
JSON

The response carries app.id, which clients compile into their URLs, and api_key.key, which goes straight into the calling service's secret manager. Do not write the response to a file that outlives the step.

Revisions and retry proofs

Read the app before a full PUT and send back the revision it answered with. A missing revision returns 400 and a stale one 409; reread and merge before retrying. The revision is a field of the app and travels only in the body — no ETag is published, because anything that compresses a response rewrites that header and a browser cannot read it cross-origin.

Creation of apps, app keys, providers and provider gateways accepts paired Idempotency-Key and X-Idempotency-Proof headers. Persist both random proofs before sending. Retry with the same body and proofs to recover the existing resource. Protected key replay expires after 15 minutes; an expired response identifies the resource and never creates another key automatically.