Management API

Everything you can configure in the console you can also manage over the API: providers, models, virtual keys, governance rules, tools, agents, and reads like usage, logs, and the map. This is what you automate from Terraform, CI, or a script.

Two different credentials

Keep these straight - they are not interchangeable:

Agent virtual key (aigw_...) - a data-plane credential. An agent sends it to the gateway (gateway.aigw.app) to call models, tools, and other agents. It cannot touch your configuration; the management API rejects it.
Management token (aigwm_...) - a control-plane credential for automation against the API (api.aigw.app). It manages configuration and reads. It cannot call models.

Create a management token

In the console, go to Settings -> API tokens -> New token. Give it a name and grant per-resource permissions. Each resource is set to one of no access, read (GET only), or read + write (read implies by write):

Tools - MCP servers + tool governance rules.
Agents - A2A agents + delegation rules.
API keys - agent virtual keys.
Catalog - model catalog + provider config.
Observability - logs, usage, audit, map, inventory, assessment.
Config - workspace settings, notifications, integrations.

Grant a token the minimum it needs (least privilege). The All read and All read + write presets are shortcuts for a read-only or full-access token.

The token is shown once on creation - copy it then. You can revoke it at any time; revocation is immediate.

Authenticate

Send the token as a bearer credential:

curl https://api.aigw.app/v1/me \
  -H "Authorization: Bearer aigwm_YOUR_TOKEN"

Each request is checked against the token’s permissions: a read (GET/HEAD) needs at least read on that resource; a write (POST/PUT/PATCH/DELETE) needs read + write. A request the token isn’t scoped for is rejected with 403 and a message like management token missing tools:write permission. Account-sensitive areas (team, billing, operator admin) and token management itself are never reachable with a token - those stay session-only.

What a token can reach

Each path maps to the resource permission it requires:

Resource	Paths
Tools	`/v1/tools` (and `mcp_config` on `/v1/me`)
Agents	`/v1/agents` (and `a2a_config` on `/v1/me`)
API keys	`/v1/api-keys`
Catalog	`/v1/models`, `/v1/providers`
Observability	`/v1/usage`, `/v1/audit`, `/v1/map`, `/v1/inventory`, `/v1/assessment`, `/v1/approvals`
Config	other tenant settings on `/v1/me`, `/v1/notifications`, `/v1/integrations/otel`

/v1/me reads are open to any token; writes there are gated by the payload (writing mcp_config needs tools:write, a2a_config needs agents:write, other settings need config:write).

Not reachable with a token: /v1/team, /v1/me/billing, /v1/admin/*, /v1/playground, and /v1/management-tokens (creating tokens is session-only, so a token cannot mint more tokens).

Examples

Read your current tools/agents governance config:

curl https://api.aigw.app/v1/me \
  -H "Authorization: Bearer aigwm_YOUR_TOKEN"

Issue an agent virtual key with a budget:

curl -X POST https://api.aigw.app/v1/api-keys \
  -H "Authorization: Bearer aigwm_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-agent","monthly_budget_cents":50000}'

Pull recent requests for a CI compliance check:

curl "https://api.aigw.app/v1/usage/requests?page=0&page_size=50" \
  -H "Authorization: Bearer aigwm_READONLY_TOKEN"