Authentication

OAuth 2.0 Authentication

When using the Foxy API, you will be able to administer all aspects of a store, covering everything that a store owner can do with through the Foxy administration.

The Foxy API uses the OAuth 2.0 open standard framework for token based authentication. Once completed, your integration is provided with tokens that it will then use to connect to a store using the API. By using OAuth, you don't need to store a user's Foxy credentials, and a user is able to see what integrations have access to their accounts and revoke that access at any time.

Common OAuth Terms

If you're not familiar with OAuth, we may use some terminology that is new to you. If so - you can read a list of common terms here.

Quick start for generating an OAuth Client

If you're wanting to try out the API but not yet ready to work through creating an integration for OAuth to generate tokens, you can create one quickly using the Foxy administration. Simply login to your store's administration, head to the "Integrations" page and click the "Get Token" button. You'll need to fill in a few details, but after submitting you'll be presented with the values to add to your code in order to use the API. For the full details on creating clients through the API itself, see Creating an OAuth Client.

OAuth 2.0 Flows

There are three common approaches for OAuth for a Foxy integration, which dictate the type of experience the user will have, and what OAuth interactions need to take place.

Standalone Integration

A Standalone Integration forms the most basic integration type - one where you are making use of a script for a specific store, rather than developing an application that will be used by an unknown number of other users.

For this type of integration, you'll just have a single OAuth Client, and will have a single Foxy User or Store authenticated through it that you're making use of with the integration. With that in mind, the quick start guide for generating an OAuth Client above is a great way to quickly get the tokens you need to get up and running.

Third Party Integration

This approach is used for integrations where users will come to your application with a Foxy store already created, and they want to authorize your application to have access to their store. See OAuth for 3rd Party Integrations for the technical flow.

Third Party OAuth flow Six steps between your user, your app, and the Foxy API: 1. User requests to connect to their store. 2. User authorizes access for your app on Foxy. 3. User is returned to your app with an auth code. 4. Your app requests the access token. 5. The API returns access and refresh tokens. 6. Your app sends requests to the Foxy API. Your User Your App Foxy API 1 2 3 4 5 6 User requests to connect to their store User authorizes access for your app User returned to your app with auth code Your app requests the access token API returns access & refresh tokens Your app sends requests to the Foxy API

Whitelabeled Integration

The whitelabelled approach is one where the user will not ever directly interact with Foxy, or at least not while signing up for a Foxy user and store. Instead they interact only with your application, and in turn your application connects to the Foxy API. See OAuth for White-Labeled Integrations for the technical flow.

Whitelabeled OAuth flow Five steps between your user, your app, and the Foxy API. The user only ever interacts with your app: 1. User creates an account with your app. 2. Your app creates a user via the API, returning a user access token. 3. User creates a store within your app. 4. Your app creates a store via the API, returning a store access token. 5. Your app sends requests to the Foxy API. Your User Your App Foxy API 1 2 3 4 5 User creates an account with your app Your app creates a user via API, returning a user access token User creates store within your app Your app creates a store via API, returning a store access token Your app sends requests to the Foxy API

Authenticating API Calls

After completing one of the OAuth integration flows detailed above, your application will have received the needed tokens to begin interacting with the Foxy API. Requests to the API need to include the access_token in the Authorization header for the protected resource you're wanting to work with, along with the version of the API you're connecting to:

FOXY-API-VERSION: 1
Authorization: Bearer 76e9237hHosdp4890sjjafu38U78HJSund7295a9

For more details on working with the API, see the API Reference.

Token Expiration

OAuth tokens can stop working for a number of reasons, so your integrations should include support for requesting new tokens when necessary.

Tokens may no longer work because:

  • A user removes your integration from their store
  • The lifetime window has expired for the token (2 hours for Access Tokens and 10 years for Refresh tokens)

A new Access Token can be requested by using the respective Refresh Token and making a request to the Foxy API - see Refreshing the Access Token for details. The Refresh Token can be renewed by completing a new Authorisation Grant through the Foxy API.

Handling Tokens Securely

As the credentials and tokens received through OAuth grant access to customer data, it's important that they're handled carefully and securely. Review Securely Storing Tokens for our recommendations.