API tokens

API tokens authenticate trusted server integrations for one selected client. The lifecycle guidance comes first, followed by the exact REST endpoint contract.

How client Basic authentication works

For client Basic authentication, your client identifier is the Basic username and a user-owned API token is the Basic password. Keep the identifier in your server configuration and the token in protected secret storage; never send the token to browser code.

Create and store a token

Use a client-user OAuth access token with the mcp scope. The access token's selected client determines the new API token's client scope.

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

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

The 201 Created response is the only response that contains the usable token:

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

Copy the token immediately into the secret manager used by your server deployment. FloPay stores only a hash, so the usable value cannot be retrieved later. If you lose it, create another token and revoke the lost one.

Never place a token in browser code, source control, logs, support tickets, or screenshots. Do not paste a real token into shared commands; all values in this guide are placeholders.

Authenticate a server integration

Configure your trusted server with the client identifier as FLOPAY_CLIENT_ID and the newly created token as FLOPAY_API_TOKEN. The client identifier remains the Basic username; FLOPAY_API_TOKEN is the Basic password.

For example, verify the credential against an existing server operation:

curl --user "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN" \
  "https://api.flopay.com/v1/users?limit=1"

curl --user constructs the HTTP Basic Authorization header. Keep this request on your server. The client identifier may be ordinary configuration, but the API token must be injected from protected secret storage and redacted from deployment output.

Rotate without downtime

Zero-downtime rotation requires an available active-token slot for the selected client. Each user can have at most 10 active tokens for that client, and creating another returns 409 Conflict. If you are at the limit, revoke only a token that is no longer in use before starting this workflow. If all 10 active tokens are still required, you cannot perform zero-downtime rotation until you can free a slot.

Both tokens remain active during the overlap:

1. Create a second token. Give it a name that identifies the integration and rotation, then store the one-time value in your secret manager. The existing token remains active.
2. Deploy the second token. Update every instance, worker, scheduled job, and cold-start configuration that belongs to the integration. Keep the old token active while the deployment completes.
3. Confirm the second token is in use. Send an authenticated request from the deployed integration and confirm it succeeds. The replacement token's lastUsedAt is supporting evidence, but it is updated on a best-effort basis and may take up to one hour to appear.
4. Revoke the old token. Do not revoke it until the replacement is confirmed across the whole deployment. After revocation, verify the integration again and remove the old value from your secret manager.

List and revoke tokens

List your active tokens for the client selected by your OAuth access token:

curl "https://api.flopay.com/v1/api-tokens" \
  -H "Authorization: Bearer $FLOPAY_ACCESS_TOKEN"

GET /v1/api-tokens returns names, descriptions, IDs, creation times, and lastUsedAt. A list response never contains a usable token or its stored hash.

Revoke a token by its returned ID:

curl --request DELETE \
  "https://api.flopay.com/v1/api-tokens/$FLOPAY_TOKEN_ID" \
  -H "Authorization: Bearer $FLOPAY_ACCESS_TOKEN"

DELETE /v1/api-tokens/$FLOPAY_TOKEN_ID returns 204 No Content. When you revoke one token, sibling tokens remain active; the revoked token disappears from later lists and can no longer authenticate.

Every token is scoped to exactly one client. If you belong to multiple clients, select each client in turn and create a separate token for each client. You may create multiple tokens for the same client when integrations or rotations need independent credentials, but no token spans clients.

Migrated credentials

Existing client API keys migrated by FloPay continue to work unchanged, so deployed integrations do not need a coordinated credential cutover. The migrated credential belongs to the client's owner and appears to that owner only as safe metadata named Migrated client API key; its usable value is not exposed again.

New integrations should create named, individually revocable, user-owned tokens through the flow above. Treat a migrated value as a compatibility credential for an existing deployment, not as a credential-distribution mechanism.

Current limits

• Cross-client tokens are not supported. Create a distinct token for every client boundary.
• Service-account tokens are not available. Every token has a human client-user owner.
• Automatic rotation is not available. Use the explicit create, deploy, confirm, and revoke sequence.
• Post-creation secret recovery is not available. Create a replacement when a usable value is lost.

API reference

• Create a token
• List tokens
• Read token metadata
• Revoke a token

REST endpoint contract

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.