Common OAuth Terms

Just to ensure we’re all on the same page - the following are terms we’ll refer to within the OAuth documentation.

OAuth Client

The OAuth Client acts as an intermediary between your integration and Foxy on behalf of the user, providing a way for users to grant access to a specific protected resource that they control. This allows a user to grant your integration access to their user or store, without needing to provide your integration with their private login. The Client will store identifying information about your integration such as its name along with your contact information and some other technical information related to your integration.

If your integration is hosted centrally in a secure location, your integration would connect to Foxy using a single OAuth Client. If your integration is individually installed/hosted by your users, each unique installation would need to dynamically create its own OAuth Client.

Client ID

The Client ID acts as the static unique identifier for your OAuth Client, and can either be set as a specific value or generated automatically by Foxy when it is initially created. It should be securely stored within your integration and is not editable once the client is created.

Once an OAuth Client is created, the Client ID can not be changed.

If your integration will be distributed and downloaded by your users, we recommend setting the Client ID manually and providing a common prefix between your integrations, as a basic way to group them together. To ensure the ID's are still unqiue, you would append a random string of characters after your prefix. For example, that could look like this in PHP:

$characters = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
$postfix = '';
for ($i = 0; $i < 30; $i++) {
    $postfix .= $characters[rand(0, strlen($characters) - 1)];
}
$client_id = "widgetsco" . $postfix;

Client Secret

The Client Secret is automatically generated alongside your Client ID and is used to verify your integration when generating access tokens and does not change. It should be encrypted and stored securely within your integration and only be known between your code and Foxy. Think of it like the master password for your integration. If the Client Secret is ever compromised, your integration could become compromised and you would need to generate a new OAuth Client for your application and have your users reconnect.

Access Token

The Access Token is included in requests to the API and contains the information needed for the API to decide if you are allowed to access a given protected resource. Think of it like the session ID for a user’s current authenticated connection, and as such it should be handled securely and protected. They are valid for 2 hours, after which time a new token needs to be generated. An Access Token has a specific scope which dictates what portions of the API it is able to interact with.

Refresh Token

The Refresh Token is valid for 10 years, and when paired with your Client ID and Secret is used to generate a new Access Token as needed. The Refresh Token should be securely stored within your system and like the Access Token has a specific scope.

Scope

A value which sets what portions of the API a given token is able to interact with. There are currently three different scopes:

client_full_access: Allows interaction with a single OAuth Client, and allows the creation of users. This is the initial scope given when creating a client to connect with the API.
user_full_access: Connected to a single user, the user record can be interacted with, including requesting a connection to their existing stores or creating a new store to be linked to the user.
store_full_access: Connected to a Foxy store, this scope allows access to all of the API that interacts with a store.

Foxy User

A Foxy user is someone who manages and configures a store. This could be an owner of the store, or someone who is working on behalf of the store owner to configure their store. Users have a many-to-many relationship with stores; a user can be granted access to many stores and a store can have many users with access to it.

Foxy Store

A Foxy Store is your home for managing your online payment system as it relates to Foxy's platform. One store will be used per organization selling online.

Authorization Server

This is an endpoint on the Foxy servers that you redirect users to from your own integration. At the endpoint the user grants access to either their existing Foxy user or store. Users will login with their Foxy credentials and choose to authorize your integration with the necessary access before being redirected back to your integration.

Foxy-Specific OAuth Terms

Standalone Integration

A Standalone Integration is one where an single integration is tied to a single OAuth Client and Foxy User or Store. The integration may be open-sourced allowing others to make use of it - but they'd provide their own OAuth Client for use within it.

3rd Party Integration

A 3rd Party Integration exists alongside Foxy, and expects their users to either have a Foxy account or create one before connecting the application to their Foxy store.

White-Labeled Integration

A White-Labeled Integration obscures Foxy from view of their users, so a user would not ever need to know that Foxy is involved. This type of integration would utilise the API to create Foxy users and stores on behalf of their application users.

Hosted Integration

A Hosted Integration could be in the form of a 3rd Party or White-Labeled integration, but is hosted centrally where your users will access it.

Distributed Integration

A Distributed Integration could be in the form of a 3rd Party or White-Labeled integration, but is also downloaded and installed/hosted by the user.