# Management API

> Manage SDK keys, proxy keys, webhook endpoints and risk weights from code, with a management key, for infrastructure as code and automation.

Last updated: 2026-09-17

The management API does from code what **Integration** and **Smart Signals > Suspect Score** do in the dashboard: issue and revoke SDK keys and proxy keys, register webhook endpoints, and set risk weights. Use it from infrastructure-as-code tools, deployment pipelines and scripts, so a staging environment and its keys, endpoints and policy can be created the same way every time.

| Resource | Operations |
| --- | --- |
| [SDK keys](https://docs.fingerly.io/reference/management/sdk-keys) | List, issue, revoke, replace allowed origins |
| [Proxy keys](https://docs.fingerly.io/reference/management/proxy-keys) | List, issue, revoke |
| [Webhook endpoints](https://docs.fingerly.io/reference/management/webhooks) | List, create, update, pause, delete, rotate the secret, send a test event, redeliver, list deliveries |
| [Risk weights](https://docs.fingerly.io/reference/management/risk-weights) | Read, save and restore the organization's and each SDK key's weights, list signals |

## Base URL

The management API is part of your region's API, under `/api/v1/management`.

```text Base URL
https://us.api.fingerly.io/api/v1/management
```

A management key is refused by any other region's API.

## Management keys

Every request is authenticated with a **management key** in the `x-api-key` header. Management keys look like `fly_mk_us_…`: they belong to your organization and region, and to no environment, because they manage keys in all three.

- Owners and admins issue them in **Integration > Management keys**. The key is shown once.
- A management key cannot issue or revoke management keys, so a leaked one cannot replace itself.
- Management keys are for servers. A request carrying a browser `Origin` header is refused, however valid the key.
- Only a keyed hash of each key is stored, as for every other key. See [security](https://docs.fingerly.io/docs/security).

> **Warning:** A management key can issue secret keys, which read your visitors' events. Keep it in a secret manager, give it the least powerful role that works, and revoke it the moment it leaks.

## Roles

Each management key acts with a role, chosen when it is issued, and may do exactly what a member with that role may do.

| Capability | Admin key | Developer key |
| --- | --- | --- |
| List, issue and revoke SDK keys, and change allowed origins | Yes | Yes |
| Manage webhook endpoints | Yes | Yes |
| Read risk weights and the signal list | Yes | Yes |
| Change risk weights and thresholds | Yes | No |
| List, issue and revoke proxy keys | Yes | No |

A request the role does not allow answers `403` with the code `insufficient_role`.

## Describe the key

```http
GET /api/v1/management/key
```

Authentication: Management key (`x-api-key: fly_mk_…`)

Every other route names your organization in its path. Read its ID here, so a tool configured with nothing but a key can find it.

**Response**

- `key_id` (string): The management key's ID.
- `organization_id` (string): The organization every management route acts on.
- `name` (string): The key's name.
- `role` (string): `admin` or `developer`.
- `region` (string): The key's data region, such as `us`.

## Conventions

- Request and response bodies are JSON, and errors use the [usual error body](https://docs.fingerly.io/reference/errors).
- Secrets, of SDK keys, proxy keys and webhook endpoints, are returned once, in the response that creates them. Every later read shows only their last four characters.
- Revoking is permanent and nothing is deleted, except webhook endpoints, which are removed.
- Changes take effect on the next request: a revoked key is refused and saved weights score the next identification.
- Changes made with a management key are attributed to no member: `created_by` and `revoked_by` are omitted.

## Errors

| Status | Code | When |
| --- | --- | --- |
| `401` | `unauthorized` | The key is missing, unknown, revoked, expired, from another region, or sent from a browser. |
| `403` | `insufficient_role` | The key's role does not allow the operation. |
| `404` | `not_found` | No such resource in the key's organization, including a path naming another organization. |
| `409` | Varies | The resource is in a state that forbids the change, such as an SDK key that is already revoked. |
| `422` | Varies | The body is not valid. `error.message` says what to fix. |

> **Tip:** The whole API is described in the [OpenAPI document](https://docs.fingerly.io/reference/openapi), which client generators and Postman can import.

- [SDK keys](https://docs.fingerly.io/reference/management/sdk-keys): Issue and revoke keys from code.
- [Risk weights](https://docs.fingerly.io/reference/management/risk-weights): Keep your scoring policy in version control.

## Example request

```bash cURL
curl "https://us.api.fingerly.io/api/v1/management/key" \
  -H "x-api-key: $FINGERLY_MANAGEMENT_KEY"
```

```ts Node.js
const response = await fetch('https://us.api.fingerly.io/api/v1/management/key', {
  headers: { 'x-api-key': process.env.FINGERLY_MANAGEMENT_KEY! },
})
const { organization_id } = await response.json()
```

## Example response

```json 200
{
  "key_id": "01a0a862-5e3f-7b01-c2d4-6f7a8b9c0d1e",
  "organization_id": "01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37",
  "name": "Terraform",
  "role": "admin",
  "region": "us"
}
```

```json 401
{
  "error": {
    "code": "unauthorized",
    "message": "the x-api-key header is not a valid management key",
    "status": 401
  },
  "request_id": "01a0a84c-0f11-7a3e-9c2d-4b5e6f708192"
}
```