Authentication

The three token types, how to get one, and what permissions they need.

Every request to the Flow Retail API carries a bearer token:

Authorization: Bearer <TOKEN>

Always over HTTPS. There are three token types, and which one you want depends entirely on what is making the call.

Token type	Use it for
Integration token	Server-to-server work — ERP, e-commerce, sync jobs. Start here.
Access token	Acting on behalf of a signed-in user.
Device token	POS hardware and managed devices.

1. Integration token — start here

A long-lived token tied to an Integration user in your tenant. This is what almost every backend integration should use.

Create one in Flow Retail Admin

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

2. Give it only the permissions it needs — see Permissions.

3. Generate an integration token for that user.

You are shown the token value once. Store it in a secret manager or an environment variable, never in source control, and treat it like a password.

Or create one over the API

Tokens can also be managed programmatically, which is what you want if you are rotating them on a schedule:

GET    /tenants/{tenantUid}/users/{tenantUserUid}/tokens
POST   /tenants/{tenantUid}/users/{tenantUserUid}/tokens
DELETE /tenants/{tenantUid}/users/{tenantUserUid}/tokens/{tenantUserTokenUid}

These require the USER_TOKEN permission. The caller needs a token that already has it — bootstrap the first one in Admin.

Use it

export FLOW_TOKEN="your-integration-token"

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

2. Access token — acting as a user

When your application acts on behalf of a signed-in user, exchange that user's auth token for a tenant-scoped 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 the returned access token on subsequent calls

POST /tenants/{tenantUid}/account accepts a user auth token only. The access token it returns is short-lived and scoped to that tenant, and is accepted by most endpoints alongside integration tokens.

3. Device token — POS hardware

Devices link once, then exchange a refresh token for a device token:

# 1. link the device
curl -X POST "https://api.flowretail.com/v2/device/{deviceCode}/link"

# 2. exchange for a device token
curl -X POST "https://api.flowretail.com/v2/device/token" \
  -H "Content-Type: application/json" \
  -d '{ "appId": "your-app-id", "refreshToken": "device-refresh-token" }'

appId is issued by Flow Retail; refreshToken comes from the linking step. Both fields are required. Neither /device/token nor /device/{deviceCode}/link requires an existing bearer token.

Permissions

A token authenticates who you are. Permissions decide what that identity may do, and they are granted to the user the token belongs to.

Endpoints declare the permission they require in the OpenAPI specification, as x-flow-permissions. The names are flat identifiers naming an area of the product — there are around seventy. Some of the most common:

Permission	Covers
PRODUCT	Products and product data
CUSTOMER	Customers and customer data
SALES_ORDER,RETURN_ORDER	Sales and return orders
PURCHASE_ORDER	Purchase orders
WAREHOUSE	Warehouses and stock
PAYMENT_METHOD	Payment method configuration
ACCOUNTING_CONFIG	Accounting configuration
REPORTING	Reports
IMPORT	Bulk import
USER_TOKEN	Creating and revoking API tokens

Where an endpoint lists more than one, as with SALES_ORDER,RETURN_ORDER, the user needs the permissions named.

The authoritative list is the specification itself — check the endpoint's reference page for the exact requirement rather than guessing, and grant least privilege. An integration that only reads products should not hold USER_TOKEN.

When authentication fails

Status	Code	Meaning
401	ErrInvalidToken	Token missing, malformed, expired or revoked
403	ErrPermissionDenied	Token is valid; the user lacks the permission
403	ErrAccessDenied	Token is valid but not allowed on this resource
403	ErrStoreAccessDenied	The user has no access to the store in the path
404	ErrNotFound	Often a tenant mismatch rather than a missing record

A 404 where you expected data usually means the token and the {tenantUid} in the path belong to different tenants.

Good practice

• Prefer integration tokens for anything server-side, and rotate them on a schedule.

• Grant least privilege — only the permissions the integration actually uses.

• Keep tokens out of source control, logs and error reports.

• Check that the token's tenant matches the {tenantUid} you are calling.

• Build against stage before production.