API tokens

All token-management operations require a client-user OAuth Bearer token with the mcp scope. The Bearer token's selected client determines the client boundary, and every operation is further scoped to the acting user. Client Basic credentials cannot manage tokens because they do not identify a human owner.

Create a token

POST /v1/api-tokens

POST /v1/api-tokens
Authorization: Bearer $FLOPAY_ACCESS_TOKEN
Content-Type: application/json

{
  "name": "Production reporting",
  "description": "Used by the nightly revenue export"
}

name is required after trimming and accepts 1–100 characters. description is optional and accepts at most 255 characters. Each user may have up to 10 active tokens for one selected client; a request above that limit returns 409 Conflict.

The 201 Created response is the only response that includes the usable token value:

{
  "id": "<token-id>",
  "name": "Production reporting",
  "description": "Used by the nightly revenue export",
  "token": "flo_<one-time-secret>",
  "createdAt": "<created-at>",
  "lastUsedAt": null
}

Creating a token adds a credential without replacing existing tokens. Copy the value immediately; FloPay stores only its SHA-256 hash and cannot return the usable value later.

List tokens

GET /v1/api-tokens

Returns the acting user's active tokens for the selected client, oldest first:

{
  "data": [
    {
      "id": "<token-id>",
      "name": "Production reporting",
      "description": "Used by the nightly revenue export",
      "createdAt": "<created-at>",
      "lastUsedAt": "<last-successful-use>"
    }
  ]
}

The list never includes usable token values or stored hashes. lastUsedAt is null until a successful Basic-auth request is recorded. Recording is best-effort and coalesced to at most once per token per hour, so recent use may take up to one hour to appear.

Read token metadata

GET /v1/api-tokens/:id

Returns the same safe metadata shape as a list entry. A token owned by another user, scoped to another selected client, or nonexistent returns the same 404 Not Found response.

Revoke a token

DELETE /v1/api-tokens/:id

Returns 204 No Content. Revocation is idempotent for a token owned by the acting user in the selected client. The revoked token disappears from subsequent lists and stops authenticating immediately; sibling tokens remain active.