Authentication

Flow Retail’s API uses Bearer tokens in the Authorization header.

There are three common ways to authenticate, depending on your use case:

1. Integration Token (server-to-server; recommended for most integrations)

2. User Auth Token → Access Token (end-user/tenant context)

3. Device Token (for POS devices)

All examples below use standard HTTPS requests with an Authorization: Bearer <TOKEN> header.

---

1. Integration Token (recommended)

Use this for backend integrations (ERPs, e-commerce, data sync jobs, etc.).

You generate a long-lived token tied to an Integration user in your tenant.

Create an Integration user & token

1. In Flow Retail Admin, create a user of type Integration user (API user) for your tenant.

2. Generate an integration token for that user.

   • You’ll receive the token value only once — store it securely (e.g., secret manager, environment variables).

   • Treat it like a password.

Use the Integration token

Include the token in the Authorization header:

Authorization: Bearer YOUR_INTEGRATION_TOKEN

Example — list reasons:

curl -X GET "https://api.flowretail.com/v2/tenants/{tenantUid}/reasons" \
  -H "Authorization: Bearer YOUR_INTEGRATION_TOKEN" \
  -H "Accept: application/json"

---

2. User Auth Token → Access Token

If your app needs to act on behalf of a logged-in user (with tenant-scoped permissions), use a user auth token and exchange it for a short-lived access token.

Flow

1. Obtain a user auth token (via your chosen login method).

2. Exchange it for an access token using:

POST /v2/tenants/{tenantUid}/account

1. Use the returned access token for subsequent calls.

Example:

curl -X POST "https://api.flowretail.com/v2/tenants/{tenantUid}/account" \
  -H "Authorization: Bearer YOUR_USER_AUTH_TOKEN" \
  -H "Accept: application/json"
# -> Use returned access token in subsequent calls

---

3. Device Token (POS devices)

For POS apps and managed devices, use the Device Authorization Flow:

1. Link or identify the device (e.g., /v2/device/{deviceCode}/link).

2. Request a device token via:

POST /v2/device/token

1. Use the returned token as the Bearer token for API calls.

Example:

curl -X POST "https://api.flowretail.com/v2/device/token" \
  -H "Content-Type: application/json" \
  -d '{ "appId": "your-app-id", "refreshToken": "device-refresh-token" }'
# -> Use returned device token as Bearer

---

Permissions & Scopes

• Endpoints declare required permissions (e.g., TENANT.ACCESS, TENANT.ADMIN) in the documentation.

• Your token must belong to a user (integration or human) that has the necessary permissions in the tenant.

---

Creating the API user (Integration user)

1. Go to Flow Retail Admin → Users.

2. Create a user of type Integration user (API user) with appropriate tenant permissions.

3. Generate an integration token and use it as the Bearer token from your backend.

---

Request format

Always send tokens in the HTTP header:

Authorization: Bearer <TOKEN>

Always use HTTPS.

---

Error handling

• 401 Unauthorized — Missing, invalid, or expired token.

• 403 Forbidden — Token is valid but lacks required permissions for the endpoint.

---

Quick start

1. Server integration (recommended):

export FLOW_TOKEN="YOUR_INTEGRATION_TOKEN"

curl -H "Authorization: Bearer $FLOW_TOKEN" \
     -H "Accept: application/json" \
     "https://api.flowretail.com/v2/tenants/{tenantUid}/reasons"

2. User auth → access token:

curl -X POST "https://api.flowretail.com/v2/tenants/{tenantUid}/account" \
  -H "Authorization: Bearer YOUR_USER_AUTH_TOKEN" \
  -H "Accept: application/json"
# -> Use returned access token in subsequent calls

3. Device token (POS):

curl -X POST "https://api.flowretail.com/v2/device/token" \
  -H "Content-Type: application/json" \
  -d '{ "appId": "your-app-id", "refreshToken": "device-refresh-token" }'
# -> Use returned device token as Bearer

---

Best practices

• Prefer Integration tokens for backend→API communication (rotate periodically).

• Apply least privilege: only assign required permissions.

• Store tokens securely; never commit them to source control.

• Implement a token rotation plan.

• Ensure your token has access to the correct {tenantUid}.