> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Management API

> Reference for the Management API: API keys with spend limits, projects with routing, budgets, controls, and guardrail overrides, organization routing policies, provider credentials, export destinations, organization settings, security rules, usage rollups, and lookups.

The Management API administers your organization's API keys, projects, routing policies, provider credentials, export destinations, settings, security rules, and usage from code, such as Pulumi, Terraform, or one-off scripts. The endpoint reference in this section has the full schemas.

## Base URL and authentication

```text
https://api-gateway.merge.dev
```

Authenticate with a management key from **API keys → Management keys** in the [dashboard](https://gateway.merge.dev/api-keys), shown once. It acts only on its own organization and can't call model endpoints.

```http
Authorization: Bearer mgmt_...
```

## Scopes

A management key's scopes are dashboard permission names. A new key gets the permissions its creator holds, so it can do through the API what that person can do in the dashboard. A call without the scope it needs returns `403`. A key keeps the scopes it was minted with, so mint a new one to pick up permissions granted later.

| Area                | Endpoints                                                                  | Writes need                                  | Reads also accept                                                                         |
| ------------------- | -------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------- |
| API keys            | `/v1/keys`                                                                 | `manage_api_keys`                            | `view_api_keys`, `view_billing`                                                           |
| Projects            | `/v1/projects`, `/controls`, `/models`                                     | `manage_projects`                            |                                                                                           |
| Routing policies    | `/v1/routing-policies`                                                     | `manage_routing`                             | Any active `mg_` API key of the organization, except in Merge for Workforce organizations |
| Credentials         | `/v1/credentials`                                                          | `manage_credentials`                         | `view_credentials`                                                                        |
| Export destinations | `/v1/export-destinations`                                                  | `manage_telemetry_export`                    | `view_telemetry_export`                                                                   |
| Organization        | `/v1/organization`                                                         | `manage_org_settings`                        | `view_org_settings`                                                                       |
| Security rules      | `/v1/dlp-rules`, `/v1/blocklist-rules`                                     | `manage_org_settings`                        | `view_org_settings`                                                                       |
| Security rules      | `/v1/organization/pi-settings`                                             | `manage_security_rules`                      | `view_security_rules`                                                                     |
| Security rules      | `/v1/projects/{project_id}/pi-settings`, `/dlp-settings`                   | `manage_security_rules` or `manage_projects` | `view_security_rules`                                                                     |
| Usage               | `/v1/organization/usage`                                                   |                                              | `view_billing`                                                                            |
| Usage               | `/v1/projects/{project_id}/usage`                                          |                                              | `view_billing`, `manage_projects`                                                         |
| Lookups             | `/v1/organization/models`, `/v1/organization/vendors`, `/v1/model-aliases` |                                              | `view_routing`, `manage_routing`                                                          |
| Lookups             | `/v1/guardrails`                                                           |                                              | `view_security_rules`, `manage_security_rules`                                            |
| Lookups             | `/v1/credits`                                                              |                                              | `view_billing`, `manage_billing`                                                          |
| Lookups             | `/v1/members`                                                              |                                              | `view_users`, `manage_users`                                                              |

Keys minted before scopes became permission names hold `manage_keys` and `read_usage`, which work as `manage_api_keys` and `view_billing`.

Walkthroughs: [Management API keys](/merge-gateway/automation/api-keys) and [Projects API](/merge-gateway/automation/projects-api). Creating an API key needs a payment method on file, except on the Free plan. There's no rotate endpoint: create the new key, then delete or disable the old one.

## Errors

An error response has a `detail` field. It's either a string or an object with a `code` to branch on and a `message`; some objects add fields, such as `count`.

```json
{"detail": {"code": "payment_method_required", "message": "Add a payment method before creating API keys."}}
```

A request body or query that fails validation returns `422` with `detail` as a list, one entry per problem, each with `loc` (where), `msg`, and `type`. A missing or invalid key returns `401`. See the [codes worth branching on](/merge-gateway/errors#management-and-platform-apis).

## Next steps

#### [Management API keys](/merge-gateway/automation/api-keys)

Create and manage API keys programmatically

#### [Projects API](/merge-gateway/automation/projects-api)

Manage project routing, budgets, and usage