# Overview

What the API covers, where it lives, and how the pieces fit.

The Feint API is how a pipeline or a script does what the console does: mint decoy credentials, record where each one was placed, retire them, and read back what the monitor has seen. It is JSON over HTTPS, authenticated with an API key you create in the console.

## Base URL

Every endpoint lives under `/v1`:

```text
https://api.feintsecurity.com/v1
```

Requests carry the key as a bearer token:

```bash
curl https://api.feintsecurity.com/v1/tokens \
  -H "Authorization: Bearer $FEINT_API_KEY"
```

[Authentication](https://feintsecurity.com/docs/authentication) covers keys and scopes.

## How the pieces fit

A **canary token** (in MITRE D3FEND terms, a [Decoy User Credential](https://d3fend.mitre.org/technique/d3f:DecoyUserCredential/)) is a real credential on a real platform — a GitLab project access token, or an AWS IAM access key — that grants next to nothing. Feint mints it, hands you the secret once, and records where you say you placed it. You put it where an intruder or their agent would look: a `.env` that is never loaded, a CI variable, a page in the internal wiki. Nothing legitimate ever uses it, so the first use is the signal. The platform records it, Feint's monitor picks it up within minutes, an **alert** is written naming the placement, the time and the source address, your team is emailed, and any [webhook endpoint](https://feintsecurity.com/docs/webhooks) you registered is POSTed to.

The API exposes both halves: the tokens, and the alerts they raise.

## Endpoints

| Method | Path | Purpose | Scope |
|---|---|---|---|
| `POST` | `/v1/tokens` | Request a canary token | `tokens:write` |
| `GET` | `/v1/tokens` | List canary tokens | `tokens:read` |
| `GET` | `/v1/tokens/{id}` | Get one canary token | `tokens:read` |
| `POST` | `/v1/tokens/{id}/rotate` | Rotate a canary token | `tokens:write` |
| `DELETE` | `/v1/tokens/{id}` | Revoke a canary token | `tokens:write` |
| `GET` | `/v1/alerts` | List canary events | `alerts:read` |
| `GET` | `/v1/alerts/{id}/records` | Get an event's records | `alerts:read` |
| `GET` | `/v1/clients` | List your clients (MSSP partners) | `tokens:read` |

## Conventions

- Timestamps are ISO 8601 in UTC; identifiers are UUIDs, except a client's, which begins `cli_`.
- New fields and endpoints appear under `/v1` without a version bump. Parse the fields you use and ignore the rest.
- Nothing is cacheable: every `/v1` response carries `Cache-Control: no-store`.
- Errors have one of two shapes, described in [Errors](https://feintsecurity.com/docs/errors).

## What the API does not do yet

Acknowledging an alert, and editing a canary's placement or metadata, are done in the [console](https://feintsecurity.com/dashboard/canaries). API keys are created and deleted there too. GitLab project tokens and AWS IAM access keys are the providers today; GitHub is in development.

The machine-readable schema is at [`https://api.feintsecurity.com/v1/openapi.json`](https://api.feintsecurity.com/v1/openapi.json).