# OpenAPI and Postman

> Download the OpenAPI 3.1 description of the Fingerly API and a Postman collection generated from it, to explore the API or generate a client.

Last updated: 2026-09-17

The client, server and management APIs are described in one OpenAPI 3.1 document. It is generated from the routes the API serves, so it lists exactly the endpoints, parameters and fields they have.

| File | Use it to |
| --- | --- |
| [openapi.json](https://docs.fingerly.io/openapi.json) | Generate a client, validate requests in tests, or import into an API tool. |
| [fingerly.postman_collection.json](https://docs.fingerly.io/fingerly.postman_collection.json) | Explore the API in Postman, one request per operation. |

```bash Download
curl -O https://docs.fingerly.io/openapi.json
curl -O https://docs.fingerly.io/fingerly.postman_collection.json
```

## What the document covers

| Tag | Operations | Key |
| --- | --- | --- |
| Client API | [Identify](https://docs.fingerly.io/reference/identify), [deferred reports](https://docs.fingerly.io/reference/deferred-report), [attestation challenges](https://docs.fingerly.io/reference/attestation-challenge) | Public |
| Server API | [List events](https://docs.fingerly.io/reference/list-events), [get an event](https://docs.fingerly.io/reference/get-event) | Secret |
| Management API | [SDK keys](https://docs.fingerly.io/reference/management/sdk-keys), [proxy keys](https://docs.fingerly.io/reference/management/proxy-keys), [webhook endpoints](https://docs.fingerly.io/reference/management/webhooks), [risk weights](https://docs.fingerly.io/reference/management/risk-weights) | Management |

- Servers are listed per region. Use the one your keys belong to.
- Each operation names the kind of key it accepts, as the `publicKey`, `secretKey` or `managementKey` security scheme. All three are sent in the `x-api-key` header.
- Every error response uses the [error body](https://docs.fingerly.io/reference/errors).
- Webhook events are not operations you call, so they are not in the document. See the [event envelope](https://docs.fingerly.io/reference/webhooks/envelope).

> **Note:** The signal report the client SDKs send, and the archived submission a single event carries, are described as plain objects. Their contents are produced and read by Fingerly and are not a public contract.

## Import into Postman

- In Postman, choose **Import** and select `fingerly.postman_collection.json`.
- Open the collection's **Variables** and set `baseUrl`, the keys you want to use, and `organizationId`.
- Send **Describe the management key** first to read your `organizationId`.

> **Tip:** Use development keys while you explore. They run the same detection, are never billed, and keep test traffic out of production.

## Generate a client

Any OpenAPI 3.1 generator can build a client from the document. Operation IDs are named for what the operation does, such as `listEvents` and `issueSdkKey`.

```bash TypeScript types
npx openapi-typescript https://docs.fingerly.io/openapi.json -o fingerly-api.d.ts
```

```bash OpenAPI Generator
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.fingerly.io/openapi.json \
  -g go \
  -o ./fingerly-client
```

To read events and verify webhooks, the [server SDKs](https://docs.fingerly.io/docs/sdks#server) are simpler than a generated client.

## Versions

The document describes API `v1`. It changes only in the ways the [versioning policy](https://docs.fingerly.io/docs/versioning) allows within a version, and every change is listed in the [changelog](https://docs.fingerly.io/docs/changelog). Write clients that ignore fields they do not know.