# Risk weights

> Read, save and restore suspect-score weights and thresholds for your organization and for individual SDK keys, and list the signals they apply to.

Last updated: 2026-09-17

Risk weights decide what each signal adds to the suspect score, and the threshold decides where `high` begins. Keep them in version control and apply them from code. See [risk weights](https://docs.fingerly.io/docs/risk-weights) for how profiles are chosen. Any management key can read weights; only **admin** keys can change them.

**Path parameters**

- `organization_id` (string, required): Your organization, from [Describe the key](https://docs.fingerly.io/reference/management/overview#describe-the-key). A path naming any other organization answers `404`.
- `platform` (string): `web`, `android` or `ios`, where a path has it.
- `sdk_key_id` (string): The SDK key, where a path has it.

## List signals

```http
GET /api/v1/management/signals/catalogue
```

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

Every signal group and the signals in it, with the platforms each applies to and its default weights, the default threshold and the maximum weight. The same for every organization. Weights are set against the signal names listed here.

## Read the organization's weights

```http
GET /api/v1/management/organizations/{organization_id}/risk-weights
```

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

**Response**

- `scope` (string): `organization`.
- `max_weight` (integer): The largest weight accepted, `10000`.
- `platforms` (PlatformWeights[]): One entry per platform.
  - `platform` (string): `web`, `android` or `ios`.
  - `scope` (string): `organization`, or `default` when nothing has been saved.
  - `stored` (boolean): Whether this scope has its own saved configuration.
  - `revision` (integer): Send it back to detect concurrent edits.
  - `suspect_threshold` (integer): The threshold.
  - `weights` (object): Signal name to weight.
  - `defaults` (object): The shipped default for each signal.
  - `signals` (string[]): The signals this platform can weight.
  - `vpn_weights_mode` (string): `method` or `confidence`.
  - `residential_proxy_weights_mode` (string): `method` or `confidence`.
  - `updated_at` (string): When the configuration was last saved.

## Save the organization's weights

```http
PUT /api/v1/management/organizations/{organization_id}/risk-weights/{platform}
```

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

**Body**

- `weights` (object): Signal name to weight, from `0` to `10000`. Replaces the stored weights. A signal left out uses its default; `0` turns it off.
- `suspect_threshold` (integer): The score at which the level becomes `high`, from `1` to `1000000`.
- `vpn_weights_mode` (string): `method` or `confidence`.
- `residential_proxy_weights_mode` (string): `method` or `confidence`.
- `revision` (integer): The `revision` a read returned. The save is refused with `409` and `weights_stale` if the weights changed since. Omit it to overwrite.

Every field is optional. Answers with the platform's configuration, which scores the next identification.

## Restore the default weights

```http
DELETE /api/v1/management/organizations/{organization_id}/risk-weights/{platform}
```

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

Saves the shipped defaults for the platform and answers with them.

## Read an SDK key's weights

```http
GET /api/v1/management/organizations/{organization_id}/sdk-keys/{sdk_key_id}/risk-weights
```

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

The same shape as the organization's, with `scope` set to `key`. A platform the key has not overridden answers with the organization's values and `stored` set to `false`.

## Save an SDK key's weights

```http
PUT /api/v1/management/organizations/{organization_id}/sdk-keys/{sdk_key_id}/risk-weights/{platform}
```

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

**Body**

- `weights` (object): Signal name to weight, from `0` to `10000`. Replaces the stored weights. A signal left out uses its default; `0` turns it off.
- `suspect_threshold` (integer): The score at which the level becomes `high`, from `1` to `1000000`.
- `vpn_weights_mode` (string): `method` or `confidence`.
- `residential_proxy_weights_mode` (string): `method` or `confidence`.
- `revision` (integer): The `revision` a read returned. The save is refused with `409` and `weights_stale` if the weights changed since. Omit it to overwrite.

Overrides the organization's profile for this key alone. Because a key belongs to one environment, this is how a new policy is tried on staging keys before it reaches production.

## Remove an SDK key's weights

```http
DELETE /api/v1/management/organizations/{organization_id}/sdk-keys/{sdk_key_id}/risk-weights/{platform}
```

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

Deletes the key's own configuration, so the key follows the organization's profile again, and answers with what the key is scored under now.

## Example request

```bash Organization
curl -X PUT "https://us.api.fingerly.io/api/v1/management/organizations/01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37/risk-weights/web" \
  -H "x-api-key: $FINGERLY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "suspect_threshold": 25,
    "weights": {
      "automation": 12
    },
    "revision": 3
  }'
```

```bash One SDK key
curl -X PUT "https://us.api.fingerly.io/api/v1/management/organizations/01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37/sdk-keys/01a0a7f3-9e05-7a61-b4c7-2d8e0f3a6b19/risk-weights/web" \
  -H "x-api-key: $FINGERLY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "suspect_threshold": 20
  }'
```

## Example response

```json 200
{
  "platform": "web",
  "scope": "organization",
  "stored": true,
  "revision": 4,
  "suspect_threshold": 25,
  "vpn_weights_mode": "method",
  "residential_proxy_weights_mode": "method",
  "weights": {
    "tor": 14,
    "automation": 12,
    "…": "…"
  },
  "defaults": {
    "tor": 14,
    "automation": 9,
    "…": "…"
  },
  "signals": [
    "tor",
    "automation",
    "…"
  ],
  "updated_at": "2026-09-16T10:02:11Z"
}
```

```json 409
{
  "error": {
    "code": "weights_stale",
    "message": "these weights have been changed since you read them",
    "status": 409
  },
  "request_id": "01a0a84c-0f11-7a3e-9c2d-4b5e6f708192"
}
```