Extension Authentication

All Fynd Commerce Extensions must use the OAuth 2.0 specification to authorize with the seller and access the Platform APIs . This guide will help you authorize your extension and obtain an access-token without using any libraries.

Recommendation

We recommend using one of our Extension helper libraries (JavaScript / Java / Python) to keep your Extension secure, avoid implementing OAuth, and focus on core logic. You can also use our CLI to generate starter code with these libraries.

If you're using an Extension helper library, you can skip this page.

Overview

OAuth 2.0 is an industry-standard protocol for authorization that allows applications to access user resources without exposing their credentials. It provides a secure way to delegate access permissions through tokens, rather than sharing login details. OAuth 2.0 enables secure communication between the Extension and Fynd Commerce on behalf of sellers. Sellers can grant specific permissions to an Extension (like accessing order or product data) without sharing their credentials. This process involves obtaining an access-token, which the Extension uses to make authenticated API requests to Fynd Commerce, ensuring that the data access is secure, controlled, and revocable.

Authentication vs Authorization

Authentication is the process of verifying the identity of the user or the Extension. To keep transactions on Fynd Commerce safe and secure, all Extensions must authenticate while making API requests.
Authorization is the process of granting permissions to Extensions. Sellers can authorize Extensions to access their data in Fynd Commerce. For example, an Extension might be authorized to access orders and product data in a Sales Channel.

API Credentials

When an Extension is created on the Fynd Partner, an API key and API secret are generated. These credentials are used to authenticate your Extension during the authorization process.

Find these credentials: Fynd Partner → Extensions → <your-extension> → Client Credentials

OAuth Flow

The following sequence diagram illustrates the authorization-code grant flow and access-token generation process:

OAuth_flow

The seller opens the Extension or initiates a request to install it on Fynd Commerce.
Fynd Commerce redirects the seller to the Extension's installation path.
The Extension redirects the seller to Fynd Commerce OAuth page.
Fynd Commerce displays the permissions page to the seller.
The seller authorizes the Extension by consenting to the requested scopes.
The Extension receives an authorization-code from Fynd Commerce.
The Extension requests an access-token using the authorization-code.
Fynd Commerce verifies the authorization-code and then issues and returns an access-token.
The Extension requests the seller's data from Fynd Commerce using this access-token.
Fynd Commerce validates the access-token and returns the requested seller data.

Step 1-2: Landing Page

After a seller open your Extension or clicks the link to install it, Fynd Commerce ensures that the seller is logged in, and redirects the seller to /fp/install path of your Extension URL with the following query parameters.

https://{extension_url}/fp/install
    ?company_id={company_id}   # Id of the seller company installing or using the Extension.
    &client_id={API_KEY}
    &cluster_url={cluster_url} # api.fynd.com

Find extension_url: Partner panel → Extensions → <your-extension> → Edit Extension → Extension URL

If you do not have an access-token, if it has has expired, or if you need to change the access scopes, you can initiate the autorization process to obtain an authorizaton-code by redirecting the seller to the following URL with the specified query parameters:

https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/authorize
    &client_id={API_KEY}
    &redirect_uri={redirect_uri}
    &response_type=code
    &scope={comma_seperated_scopes}
    &state={random_string}

Query parameters

Parameter	Value
company_id	The Company ID where the extension is to be installed.
client_id	The Extension API key.
redirect_uri	The URL to redirect after the seller authorizes the Extension. Typically `<extension-url>/fp/auth` is used.
response_type	`code`
scope	A comma-separated list of access scopes (List of all scopes).
state	A random string used for validation.

If the access scopes have changed or if the seller is installing the Extension for the first-time, Fynd Commerce will show the seller the permission page and get consent.

Step 6: Authorization-code Grant

After the seller consents to the access scopes requested by the Extension, Fynd Commerce redirects them to the redirect_uri provided in the previous step, with the following query parameters:

https://{redirect_uri}          # Same URI from the previous authorization request.
    ?code={authorization_code}  # Authorization-code.
    &state={random_string}      # Same random string as the previous request.
    &client_id={API_KEY}        # Extension API key.
    &company_id={id}            # Company ID where the Extension is being installed.

If the seller rejects the access scopes, the authentication flow will be interrupted, and you will not receive any API call on this redirect_uri.

Safety Check

For security, ensure that the state matches the one you previously provided to /oauth/authorize page, and also validate the client_id against your API key.

Step 7-8: Access-token

Once you have the authorization-code, you can now obtain an access-token. There are two types of access-token for interacting with the Fynd Commerce APIs: Offline and Online tokens.

	Offline token	Online token
Use Case	Ideal for background tasks like responding to webhooks or performing maintenance activities.	Best suited when you want to link the seller with all the activities in the API logs.
Expiry	Valid for 1 hour. Can be refreshed indefinitely using the refresh token process.	Valid for 6 hours. Automatically renews the access-token in the background upon expiry.
Tagging	A system user, created when an Extension is registered, is linked with all the API calls.	The authorizing seller is linked with all the API calls.

Offline Token

To obtain this offline access-token, send a POST request to the following URL with the given headers and payload:

URL

POST https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/offline-token

Payload

{   // Payload for "/oauth/offline-token"
    grant_type: "authorization_code",
    code: {authorization_code},       // Obtained in the previous step.
    client_id: {API_KEY},
    client_secret: {API_SECRET},
    scope: {comma_seperated_scopes}   // Scopes needed for offline access.
}

Headers

Header	Value
Authorization	`Basic {API_KEY}:{API_SECRET}`
Content-Type	`application/json`

Response

Upon a successful request, Fynd Commerce will respond with an access-token.

{   // Response for "/oauth/offline-token"
    access_token: "<token>",
    token_type: "<token_type>",
    expires_in: "<ttl>",
    expires_at: "<expires_at>",
    refresh_token: "<refresh_token>",
    scope: "<comma_seperated_scopes>"
}

note

The Authorization header requires base64 encoding of {API_KEY}:{API_SECRET}. Example in bash:

"Authorization: Basic $(echo -n 'e85d3bd3e7ed8:Ul7D1nzof' | base64)"

Refreshing Offline Token

To refresh your offline access-token, make the same POST request as above, but update the payload:

Payload

{   // Payload for access-token refresh
    grant_type: "authorization_code",
    code: {authorization_code},     // Obtained during authorization process (step 6).
    refresh_token: {refresh_token}  // Obtained along with the offline access-token.
}

URL, Headers & Response

Same as for obtaining the offline token.

Online Token

To obtain an online access-token, you can send a POST request to the /oauth/token URL with the same headers and a lighter payload.

URL

POST https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/token

Payload

{
    grant_type: "authorization_code",
    code: {authorization-code}      // Obtained during authorization process (step 6).
}

Headers

Same as for obtaining the offline token.

Response

{   // Response for "/oauth/token"
    access_token: "<token>",
    token_type: "<token_type>",
    expires_in: "<ttl>",
    expires_at: "<expires_at>",
    scope: "<comma_seperated_scopes>",
    current_user: "<user_details>"
}

Step 9-10: API Requests

Once you've obtained an API access-token, you can send authenticated requests to Fynd Commerce to get the seller's data. All the requests should have a valid access-token in header with the following format:

Header	Value
Authorization	`Bearer {access_token}`

Learn More

Learn more about Fynd Storefront GraphQL API and Fynd Platform API .

Example

To list all products available in the catalog using the Platform REST API in cURL, you can run:

curl -X GET "https://api.fynd.com/service/application/catalog/v1.0/products/"
     -H "Authorization: Bearer xI8snq31S"

If an API call fails due to an expired access-token:

For offline tokens, renew the access-token using a refresh token.
For online tokens, restart the OAuth process to get a new access-token.

Overview​

API Credentials​

OAuth Flow​

Step 1-2: Landing Page​

Step 3-5: Permissions & Consent​

Step 6: Authorization-code Grant​

Step 7-8: Access-token​

Offline Token​

Refreshing Offline Token​

Online Token​

Step 9-10: API Requests​

Example​

Overview

API Credentials

OAuth Flow

Step 1-2: Landing Page

Step 3-5: Permissions & Consent

Step 6: Authorization-code Grant

Step 7-8: Access-token

Offline Token

Refreshing Offline Token

Online Token

Step 9-10: API Requests

Example