# Management API overview

Automate the shipped organisation, project, flag, runtime-key, and audit workflows.

The public Management API is a preview control-plane automation surface. It supports a narrow set of
discovery, flag, runtime-key, and audit workflows. It does not reproduce every console action.

Use it for repeatable provisioning and credential operations owned by trusted automation. Keep human
administration and unsupported workflows in the console.

> [!NOTE] Preview surface
> Shipped routes are usable, but scopes and workflow coverage may expand before
> the Management API is stable. Use versioned `/v1` contracts and review release
> notes before broad automation.

## Create a management key

Owners and admins create a key from **Organisation settings → Access keys**. Select only scopes needed
by the automation and copy the raw secret when it is shown.

Store the key in an automation secret manager. Do not put it in source control, command-line arguments,
build output, logs, or error reports.

A management key is separate from a server runtime key and a browser client key. Runtime keys cannot
call Management routes, and management keys cannot evaluate flags.

## Authenticate requests

Send the key as a Bearer token:

```sh
curl https://api.featuregate.dev/v1/organisations \
  -H "Authorization: Bearer $FEATUREGATE_MANAGEMENT_KEY"
```

Use `Content-Type: application/json` for request bodies. Keep the production API base URL in one
automation configuration rather than repeating it in every script.

## Shipped scopes and workflows

| Workflow                       | Scope                           |
| ------------------------------ | ------------------------------- |
| Discover organisations         | `management:organisations:read` |
| Discover and read projects     | `management:projects:read`      |
| Read project environments      | `management:environments:read`  |
| Read flags                     | `management:flags:read`         |
| Create and configure flags     | `management:flags:write`        |
| List runtime key metadata      | `management:runtime-keys:read`  |
| Create and revoke runtime keys | `management:runtime-keys:write` |
| Read project audit events      | `management:audit:read`         |

Grant read scopes separately from write scopes when a consumer only inventories state. Split keys
when provisioning and audit export have different owners or rotation schedules.

## Resource discovery

Resolve organisations and projects through API reads. Preserve stable IDs and environment keys rather
than parsing console URLs or depending on display order.

Environment list responses include active and archived resources. Check lifecycle before choosing an
automation target.

Flag creation defines identity and type. Environment configuration is a separate operation. A created
flag is not usable until at least one intended environment receives a typed fallback.

## Response and pagination conventions

Successful list endpoints wrap resources in a named collection. Audit events use one-based `page` and
bounded `limit` query parameters and return `page`, `pageCount`, `pageSize`, and `totalCount`.

Do not invent cursor handling for endpoints that expose page-based pagination. Follow the generated
reference for each response shape.

API errors use the shared envelope with a stable code and human-readable message. Branch automation on
status and code, not the exact wording of a message.

## Error policy

| Status | Automation response                                          |
| ------ | ------------------------------------------------------------ |
| `400`  | Correct request or resource identifiers                      |
| `401`  | Replace the invalid or revoked management key                |
| `403`  | Check scope, resource visibility, and organisation lifecycle |
| `429`  | Respect retry information and reduce pressure                |
| `5xx`  | Retry only idempotent work with bounded backoff              |

Never log raw request authorization. Redact bodies when they can contain configuration or one-time
runtime secrets.

## Current limits

The preview does not manage:

- Organisation membership or roles.
- Billing or plan state.
- Browser client keys.
- Targeting rules or percentage rollouts.
- Tags.
- Project lifecycle or transfer.
- Organisation closure.
- Account authentication or sessions.

Do not publish an internal CLI or private package as a customer integration. Use direct HTTP against
the generated contract until a public client is released.

Related pages: [Provision flags](/docs/automation/provision-flags),
[Rotate runtime keys](/docs/automation/rotate-runtime-keys), and the generated
[API reference](/docs/api/reference/getting-started).