# Proxy keys

> List, issue and revoke the proxy keys your first-party proxies authenticate with. Admin management keys only.

Last updated: 2026-09-17

Proxy keys let a proxy on your own domain forward identify requests with the visitor's real details. See [proxy integrations](https://docs.fingerly.io/docs/proxy-integrations). Only **admin** management keys can manage them; a developer key answers `403`.

**Path parameter**

- `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`.

## List proxy keys

```http
GET /api/v1/management/organizations/{organization_id}/proxy-credentials
```

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

**Response**

- `credentials` (ProxyKey[]): Every proxy key, oldest first, revoked keys included.
  - `id` (string): The key's ID.
  - `name` (string): The key's name.
  - `environment` (string): `production`, `staging` or `development`.
  - `region` (string): The key's data region.
  - `prefix` (string): The start of the secret, such as `fly_px_us_production`.
  - `last4` (string): The last four characters of the secret.
  - `status` (string): `active` or `revoked`.
  - `last_used_at` (string): When the key last authenticated a request.
  - `expires_at` (string): When the key stops working.
  - `created_at` (string): When the key was issued.
  - `revoked_at` (string): When the key was revoked.

## Issue a proxy key

```http
POST /api/v1/management/organizations/{organization_id}/proxy-credentials
```

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

**Body**

- `name` (string, required): What the key is called.
- `environment` (string, required): The environment of the public keys it will forward: `production`, `staging` or `development`.

Answers `201` with `credential`, a proxy key as above, and `secret`, the whole key, shown once.

## Revoke a proxy key

```http
POST /api/v1/management/organizations/{organization_id}/proxy-credentials/{proxy_credential_id}/revoke
```

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

Refuses the key from the next request on, and answers with the revoked key.

## Example request

```bash cURL
curl -X POST "https://us.api.fingerly.io/api/v1/management/organizations/01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37/proxy-credentials" \
  -H "x-api-key: $FINGERLY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cloudflare Worker",
    "environment": "production"
  }'
```

## Example response

```json 201
{
  "credential": {
    "id": "01a0a861-4d2e-7a90-b1c3-5e6f7a8b9c0d",
    "name": "Cloudflare Worker",
    "environment": "production",
    "region": "us",
    "prefix": "fly_px_us_production",
    "last4": "M2dT",
    "status": "active",
    "created_at": "2026-09-16T09:20:03Z"
  },
  "secret": "fly_px_us_production_…"
}
```

```json 403
{
  "error": {
    "code": "insufficient_role",
    "message": "only an owner or an admin may manage proxy integrations",
    "status": 403
  },
  "request_id": "01a0a84c-0f11-7a3e-9c2d-4b5e6f708192"
}
```