API Authentication

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Author:

Fluent Commerce

Changed on:

9 May 2025

Overview

APIs use authorization to ensure that client requests access data securely. This can involve authenticating the sender of a request and verifying that they have permission to access or manipulate the relevant data. The below request will return a bearer token. This token can then be used in the header of subsequent API calls to confirm authentication.

Key points

Overview
Operations
Models

Property	Value
URL	`<root_url>/oauth/token?<API Credentials>`
Methods	`POST`
Scheme	`https`
Permissions
Content-Type	`application/json`

Operations

[POST] /oauth/token?{API Credentials} Authentication Endpoint

This endpoint uses the provided username, password, client ID & client secret to generate an authentication token.

Parameters

API Credentials

The customer/partner will receive an email from Fluent Commerce that will contain the following information:

Credentials Information

In case of customer or partner did not receive the credential details, please contact one of the Fluent Friendly staff.

Name	Default Value	Multiple?	Description
API Key		❌	This API key is to be used in the Store Locator and other Javascript widgets
API Client ID and secret		❌	The API Client grants the retailer access to the content via the Fluent REST API. Each retailer will have one API Client
User account details		✅	These are the details that the user needs to access APIs and Fluent Commerce apps such as the Fluent Console and ServicePoint Instore App. An API Client can have multiple users, e.g., for different applications that require different levels of API access.

Responses

Response Content Type:

`application/json`

Code	Description
200	Successful Operation
400	Client Error - Bad Request
401	Authorization Error - Invalid Bearer Token / No permission
403	Authorization Error - Forbidden
404	Client Error - Not Found
500	Server Error

Example Requests

An Authentication API request containing

`username`

and

`password`

parameters:

`https://ACCOUNT.sandbox.api.fluentretail.com/oauth/token?username=fluent-api&password=fluent-staging&scope=api&client_id=fluent-api&client_secret=ca5ce9a8-2f2e-4b4a-b8da-767f79fc81a9&grant_type=password`

1{
2    "access_token": "cf02e220-86ea-408d-9b80-fb55f517725b",
3    "token_type": "bearer",
4    "refresh_token": "xlUuQ5e-h9Y2pRw5G4Du4fAdRfk",
5    "expires_in": 86386,
6    "scope": "api",
7    "Retailer_id": 1,
8    "FirstName": "Fluent",
9    "LastName": "Commerce",
10    "Roles": []
11}

Language: json

Name: Example Success Response

Description:

The

`refresh_token`

will be included in the response only if refresh tokens are enabled for the account and Single Sign-On (SSO) is not enabled.

1{
2    "errors": [
3        {
4            "code": "400",
5            "message": {
6                "error": "invalid_grant",
7                "error_description": "Bad credentials"
8            }
9        }
10    ]
11}

Language: json

Name: Example Error Response

Description:

An example authentication error response indicating that the supplied username and password combination were invalid

An Authentication API request using the FLUENT_INTEGRATION client:

`https://ACCOUNT.sandbox.api.fluentretail.com/oauth/token?client_id=FLUENT_INTEGRATION&scope=retailer&username=fluent-api&password=fluent-staging&client_secret=ca5ce9a8-2f2e-4b4a-b8da-767f79fc81a9&grant_type=password`

The FLUENT_INTEGRATION client is designed specifically for integrations with the Fluent platform as it has the refresh token functionality enabled by default. The following parameters are required:

```
`client_id=FLUENT_INTEGRATION`
```
```
`scope=retailer`
```

Please note that the

`client_secret`

is unique to the FLUENT_INTEGRATION client_id, and it's client_secret can be obtained by submitting a ticket through our support platform.

Refresh tokens are currently used in Mystique to ensure a user remains logged in when they have a browser session open. The access token is checked every 30s to validate how much time is remaining until expiry. If the access token is close to expiring, the refresh token is automatically used to retrieve a new access token.

1{
2    "access_token": "O1ogEE-LnvZIp_c3DCgKXfhiJII",
3    "token_type": "bearer",
4    "refresh_token": "fx25qnHPXER80FUx-Qo9ce02ITs",
5    "expires_in": 1799,
6    "scope": "retailer",
7    "Retailer_id": 5,
8    "Roles": ["RETAILER"],
9    "FirstName": "Fluent",
10    "LastName": "Commerce"
11}

Language: json

Name: Example Success Response When Authentication Using The FLUENT_INTEGRATION Client ID

Description:

The response of an authentication request using the

`FLUENT_INTEGRATION`

client will include a

`refresh_token`

as that functionality is enabled by default.

1{
2    "error": "invalid_client",
3    "error_description": "Bad client credentials"
4}

Language: json

Name: Example Error Response When Authentication Using The FLUENT_INTEGRATION Client ID

Description:

The

`FLUENT_INTEGRATION`

client uses a separate client secret to other credentials. Please contact our support platform for help with obtaining the correct secret for this client.

An Authentication API request with the

`username`

and

`password`

parameters substituted with a

`refresh_token`

and the

`grant_type`

set to

`refresh_token`

`https://ACCOUNT.sandbox.api.fluentretail.com/oauth/token?refresh_token=zVusnPsE3dPjXEi4b1p6DYHoL8E&scope=api&client_id=fluent-api&client_secret=ca5ce9a8-2f2e-4b4a-b8da-767f79fc81a9&grant_type=refresh_token`

1{
2    "access_token": "cf02e220-86ea-408d-9b80-fb55f517725b",
3    "token_type": "bearer",
4    "refresh_token": "xlUuQ5e-h9Y2pRw5G4Du4fAdRfk",
5    "expires_in": 86386,
6    "scope": "api",
7    "Retailer_id": 1,
8    "FirstName": "Fluent",
9    "LastName": "Commerce",
10    "Roles": []
11}
12

Language: json

Name: Example Success Response When Requesting A New Access Token Using A Refresh Token

Description:

The response body mirrors that of a standard authentication request when using a refresh token to request a new access token.

1{
2    "error": "invalid_grant",
3    "error_description": "Invalid refresh token"
4}

Language: json

Name: Example Error Response When Reusing A Refresh Token

Description:

Refresh tokens are single-use. Trying to reuse then will result in an "Invalid refresh token" error.

Models

Response Model

Key	Type	Mandatory?	Possible Values	Constraints	Description
access_token	String	✅			The access token string as issued by the authorization server
token_type	String	✅			The type of token. This will typically be the string “bearer”
expires_in	Integer	❌			If the access token expires, this field will return a value in seconds until the token expires. This value does not affect the expiry of the `refresh_token`
scope	String	❌
refresh_token	String	❌			Refresh tokens can be used to fetch a new access token from the Authentication API without needing to pass the username and password parameters. Refresh tokens are single-use and allow integrations to renew access tokens before expiry, without the need to store sensitive credentials.
Retailer_id	Integer	❌			This is a unique ID associated with the retailer
Roles	[String]	❌			An array of the Roles associated with the returned token
FirstName	String	❌			The first name of the user account that requested the token
LastName	String	❌			The last name of the user account that requested the token

Error Model

Key	Type	Possible Values	Description
errors	Array		List of errors
code	String	400, 401, 403, 404, 500	error code
message	String		description of the error