Creating an OAuth Client

An OAuth Client acts as the authentication middleman between your integration and the Foxy API - allowing users to authenticate with your integration without having to provide you with their actual Foxy credentials. The client also provides some basic information to Foxy about your integration, such as it's name and contact details.

Depending on the type of integration you're developing, you'll either need one client that represents your integration, or an individual client for each installation of your integration.

Standalone Integration

If you're developing a standalone integration for a single store, you can quickly generate a client with a store_full_access scoped token set from within 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 client_id and client_secret for your OAuth Client, and the access_token and refresh_token with a store_full_access scope linked to the current store. Copy these values to your side and store them securely - as they won't be accessible again after that point. Once generated though you can begin interacting with the API, and as needed generate a new Access Token using the Client ID and Secret and the Refresh Token.

Hosted Integration

For an integration that you host centrally, your integration will just need a single OAuth Client. This means you should only need to complete this step once for your integration with Foxy.

Distributed Integration

If your integration will be downloaded and installed/hosted by your users themselves, each individual instance of your integration will need it’s own OAuth Client. As your users will have access to the codebase, you can’t keep the necessary sensitive details like the Client Secret and Access/Refresh Tokens private when stored within the code.

You will instead need to dynamically create the client within your integration as required when users install/initiate it through the Foxy API.

Create an OAuth Client

To get the URI needed to create a client, first perform a simple GET request to the API home page. This will return all of the base URI's that you can access without authentication.

➔ curl -H "FOXY-API-VERSION: 1" https://api.foxycart.com

{
    "_links": {
        "curies": [
            {
                "name": "fx",
                "href": "https://api.foxycart.com/rels/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://api.foxycart.com/",
            "title": "Your API starting point."
        },
        "fx:property_helpers": {
            "href": "https://api.foxycart.com/property_helpers",
            "title": "Various helpers used for determing valid property values."
        },
        "https://api.foxycart.com/rels": {
            "href": "https://api.foxycart.com/rels",
            "title": "Custom Link Relationships supported by this API."
        },
        "fx:create_client": {
            "href": "https://api.foxycart.com/clients",
            "title": "Create a client via POST."
        },
        "fx:token": {
            "href": "https://api.foxycart.com/token",
            "title": "The OAuth endpoint for obtaining a new access_token using an existing refresh_token. Post www-form-url-encoded data as follows: grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}",
            "type": "application/json"
        }
    },
    "message": "Welcome to the FoxyCart API! Our hope is to be as self-documenting and RESTful as possible. Please let us know if you have any questions by emailing us at helpdesk@foxycart.com. As a last resort, you could read the documentation at http://wiki.foxycart.com. Your first action should be to create an OAuth Client, then a user, followed by a store."
}

As returned as part of the API home page, POST to the fx:create_client link relationship, passing in the necessary parameters as defined within the API reference.

For a distributed integration, the project_*, company_* and contact_* parameters will probably be the same for all of your dynamically created OAuth Clients. The client_id needs to be unique per integration though, and while the API can auto-generate a random Client ID value for you if left blank, we recommend you generate your own with a common prefix for your integration. This way all instances of clients for your integration are loosely grouped together. Begin the value with your prefix, then append 30 or so random characters. The redirect_uri will be relative to where the user has installed your integration.

➔ curl -H "FOXY-API-VERSION: 1" https://api.foxycart.com/clients -d "redirect_uri=https://www.example.com/oauth&project_name=ACME Widgets&company_name=ACME&contact_name=John Doe&contact_email=john.doe@example.com&contact_phone=555-123-4567"

{
    "_links": {
        "curies": [
            {
                "name": "fx",
                "href": "https://api.foxycart.com/rels/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://api.foxycart.com/clients/100",
            "title": "This Client"
        },
        "fx:attributes": {
            "href": "https://api.foxycart.com/clients/100/attributes",
            "title": "Attributes for This Client"
        }
    },
    "message": "client 100 created successfully.",
    "token": {
        "access_token": "a0e923jH7fgpsd932hSHg2PFf390Sm7Js9302d60",
        "expires_in": 7200,
        "token_type": "Bearer",
        "scope": "client_full_access",
        "refresh_token": "2e504hOsj7270Ynsp7820Sky3k46rGNP325S57ed"
    },
    "client_id": "client_N9a5EgHjIQ95hsd0sD27",
    "client_secret": "Vsz26ue38QdSIgIQSk4rDh9bDBmTQ4NVSphCRPmL"
}

In response, if successful, you will receive the client_id, client_secret, refresh_token and access_token, along with some other values.

The client_id and client_secret are like the master username and password for your OAuth Client, and are used when performing certain OAuth requests like refreshing access tokens. If the client_secret is ever compromised, your integration could also be compromised. This would require a new OAuth client to be created and in turn require each of your users to re-authenticate their stores to your integration.

The refresh_token and access_token are needed to connect to the API authorized as your OAuth Client with the client_full_access scope.

You should securely store the OAuth Client ID and Secret within your integration to allow it to make OAuth requests in the future. You should only store the client_full_access scoped Refresh Token within your application if it specifically needs to be able to make changes to your OAuth Client as part of the integration.

Reconnect to the API

After creating the Client, you can then access the API again, except now authenticated with your client_full_access tokens you just received. To do that, pass the Authorization Bearer headers with your request, passing the access_token you just received when creating the client:

Authorization: Bearer <access_token>

That would look something like this:

➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a0e923jH7fgpsd932hSHg2PFf390Sm7Js9302d60" https://api.foxycart.com

{
    "_links": {
        "curies": [
            {
                "name": "fx",
                "href": "https://api.foxycart.com/rels/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://api.foxycart.com/",
            "title": "Your API starting point."
        },
        "fx:property_helpers": {
            "href": "https://api.foxycart.com/property_helpers",
            "title": "Various helpers used for determing valid property values."
        },
        "https://api.foxycart.com/rels": {
            "href": "https://api.foxycart.com/rels",
            "title": "Custom Link Relationships supported by this API."
        },
        "fx:reporting": {
            "href": "https://api.foxycart.com/reporting",
            "title": "The Reporting API Home."
        },
        "fx:client": {
            "href": "https://api.foxycart.com/clients/100",
            "title": "The current client for your authentication token"
        },
        "fx:create_user": {
            "href": "https://api.foxycart.com/users",
            "title": "Create a User via POST"
        },
        "fx:token": {
            "href": "https://api.foxycart.com/token",
            "title": "The OAuth endpoint for obtaining a new access_token using an existing refresh_token. Post www-form-url-encoded data as follows: grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}",
            "type": "application/json"
        }
    },
    "message": "Welcome to the FoxyCart API! Our hope is to be as self-documenting and RESTful as possible. Please let us know if you have any questions by emailing us at helpdesk@foxycart.com. As a last resort, you could read the documentation at http://wiki.foxycart.com. Your first action should be to create an OAuth Client, then a user, followed by a store."
}

Once connected to the API, you will notice in the response that we have some new link relationships available with our new scope. These include the ability to create new users, view/modify your OAuth Client and a reporting endpoint where you can see if a user or store already exists.

Connect to a Foxy User or Store

With the OAuth Client details in hand, you can now begin to create or connect Foxy Users and Stores with your integration. For details on how to approach that, review the technical flow for a Third Party OAuth Integration or a White-Labeled OAuth Integration.