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.

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 the OAuth for 3rd Party Integrations page for more information on this integration type.

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 the OAuth for White-Labeled Integrations pages page for more information on this integration type.

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. 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. Check out our overview on securely storing OAuth credentials.