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}

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

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 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}

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

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

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

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 that requested the token
LastName	String	❌			The last name of the user 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