API Authentication
Author:
Fluent Commerce
Changed on:
6 Feb 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``password``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`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:
[Warning: empty required content area]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`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:
[Warning: empty required content area]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`An Authentication API request with the
`username``password``refresh_token``grant_type``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}
12Language: json
Name: Example Success Response When Requesting A New Access Token Using A Refresh Token
Description:
[Warning: empty required content area]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 | ||
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 |
