> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/api/introduction/authentication.md).

# 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](https://admin.flowretail.com/), 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
```

3. 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
```

3. Use the returned token as the Bearer token for API calls.<br>

#### 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](https://admin.flowretail.com/) → 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}.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flowretail.com/api/introduction/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.