API token management

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