Shopfront Developers

Authentication

Shopfront uses OAuth 2.0 to authenticate applications. If you're not familiar with it we would highly suggest checking it out and understanding the standard and framework.

Getting Started

Before you begin developing your integration, you'll need to register it as an application by creating an account. Once you've created your application, it will be assigned a random client_id and client_secret. Your client_secret should NOT be shared or committed to source.

If your client_secret is found to have been exposed to the internet, your application will be instantly revoked from all Vendors and all of your applications will be prevented from being authorised until Shopfront is satisfied you have secured your application.

Authorization Flow

In order to ensure secure authentication for Vendors and their users, we use Bearer Tokens to control access to resources.

In order to get an access token for your application you must complete the following:

Initial Authorization

In order for the user to authenticate your application you must direct them to one of the following addresses:

  • https://[vendor_subdomain].onshopfront.com/oauth/authorize (preferred)
  • https://onshopfront.com/oauth/authorize

Both address provide the same functionality to the API, however it is more convenient for users to authenticate with their Vendor already specified.

When redirecting, you're required to pass the following as GET parameters

  • client_id: The client_id issued when you created your application,
  • redirect_uri: The URL to redirect back to (it must match the URL you provided when setting up the application),
  • response_type: This must equal code,
  • scope: A space separated list of scopes.

The following GET parameters are optional (but are recommended)

  • state: A string passed back to the application once authorization is completed (this is useful for assisting with the prevention of CSRF attacks).

An example URL looks like the following:

https://example.onshopfront.com/oauth/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fexample.com%2Fredirect&response_type=code&scope=see_products%20create_products&state=ABC

Authorization Result

Following the redirect the user then selects to authenticate the application or not.

If the user declines the integration, they are redirected back to the redirect_uri provided with the following GET parameters:

  • error: The error that occurred (user declined),
  • state: The state provided originally if specified.

If the user approves the integration, they are also redirect back to the redirect_uri provided but with the following GET parameters:

  • code: A temporary code used to retrieve an access token,
  • state: The state provided originally if specified.

We are aware of an issue with some PHP configurations that have the subhosin patch not being able to read the code parameter as it sometimes exceeds the default 512 character limit for a URL. You can fix this by either: - Increasing the limit by adding subhosin.get.max_value_length = [limit] where [limit] is a value of your choosing, - Manually parsing the URL by using $_SERVER['REQUEST_URI'].

Getting an Access Token

Once authorization has been completed successfully, you will be able to request an access token for your application. To do this you must send a POST request to https://onshopfront.com/oauth/token with the following fields in a JSON body:

  • client_id: The client_id issued when you created your application,
  • client_secret: The client_secret issued when you created your application,
  • code: The temporary code provided from a successful authorization,
  • redirect_uri: The URL to redirect back to (it must match the URL you provided when setting up the application),
  • grant_type: This must equal authorization_code.

Upon receiving this information, we will return a JSON response that contains the following data:

  • token_type: The type of token (in this case Bearer),
  • access_token: The access token to use for requests,
  • refresh_token: The refresh token to use to refresh the access_token,
  • expires_in: The number of seconds until the access_token expires.

Refreshing Access Tokens

Once your access token expires you'll need to refresh it in order to get a new one. To do this you must send a POST request to https://onshopfront.com/oauth/token with the following fields in a JSON body:

  • client_id: The client_id issued when you created your application,
  • client_secret: The client_secret issued when you created your application,
  • refresh_token: The latest refresh token that corresponds to the access token,
  • grant_type: This must equal refresh_token.

Upon receiving this information, we will return a JSON response that contains the following data:

  • access_token: The access token to use for requests,
  • refresh_token: A new refresh token to use in the future,
  • expires_in: The number of seconds until the access_token expires.

Once you receive this data, you'll need to update your access_token and refresh_token as previous ones will no longer be valid.

Next Steps

Now that your application is authenticated you're ready to start developing your application!

Application still not authenticated? Check out our how-to guide on authentication.

Making API Calls

Once your application has been authenticated and you have an access token, you can begin to make requests to the API by providing the access_token in the Authentication header. For more information, check out the Headers section below.

A Note About Scopes

Shopfront supports and highly recommends the use of scopes (without them you won't qualify for our partner program). Scopes are essentially permissions that your application requests from the user that allow you to perform a limited amount of functions.

Scopes are only able to be requested during the initial authorization step, if your application later requires more scopes, you'll need to send the user back through the initial authorization.

Currently, if you don't request any scopes, you'll receive access to all scopes however this will prevent you from qualifying for our partner program.

Users are only able to approve scopes that match what permissions they currently have available to them (for example, a user who can't create products cannot approve an application which requests the create_products scope).

In order to determine which scope you need to request, you should look at our documentation which will state the required scopes for the function you're performing.