API Authentication
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 |
|
Methods |
|
Scheme |
|
Permissions | |
Content-Type |
|
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:
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:
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 | ||
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 |