OAuth for White-Labeled Integrations
The following page details the technical flow of creating an OAuth client and creating a Foxy user and store from within your application, without them ever needing to know that Foxy is involved. If you instead want Foxy to handle user and store creation directly with the user and then allow you to connect to their existing account, take a look at the OAuth for 3rd Party Integrations page.
Register your OAuth Client
Check out the Creating an OAuth Client page for information on setting up a client for your integration
Create a Foxy User
With your OAuth Client created and credentials stored, you can now begin creating Foxy users. A user is needed first before you can create a store if needed.
To create a user, connect to the API authorized through the OAuth client you just created. 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 a0e16952dc7b0afasd9abfc0bc0c54ee0202d60" 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."
}Then, from the API home page, POST to the fx:create_user link relationship. You can see a full list of the parameters you can pass on the API Reference for the create_user rel. At a minimum, the first_name, last_name and email is required.
If successful, in response you will receive the access_token and refresh_token with user_full_access scope to this newly created user. You will need to securely store these tokens to allow you to connect to this user again in the future to make changes or create new stores connected to it.
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a0e923jH7fgpsd932hSHg2PFf390Sm7Js9302d60" https://api.foxycart.com/users -d "first_name=John&last_name=Doe&email=johndoe@example.com"
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/users/46000",
"title": "This User"
},
"fx:attributes": {
"href": "https://api.foxycart.com/users/46000/attributes",
"title": "Attributes for This User"
},
"fx:stores": {
"href": "https://api.foxycart.com/users/46000/stores",
"title": "Stores for This User"
}
},
"message": "user 46000 created successfully.",
"token": {
"access_token": "b4h50ShRPJ2967DWK6h20shyYWMP920dUEBnric5",
"expires_in": 7200,
"token_type": "Bearer",
"scope": "user_full_access",
"refresh_token": "cee5hnp1UYp3921HMI067S30POeo79bnWMBid25a"
}
}Create a Foxy Store
With a user account created, you can then use it to create a store - with the process being quite similar to creating a user.
To create a store, access the API home page with the Authorization Bearer header for the respective user_full_access scoped access_token.
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer b4h50ShRPJ2967DWK6h20shyYWMP920dUEBnric5" 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:user": {
"href": "https://api.foxycart.com/users/46000",
"title": "Your API home page."
},
"fx:stores": {
"href": "https://api.foxycart.com/users/46000/stores",
"title": "Your stores"
},
"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."
}Looking at the links that are now available on the homepage - you'll see that we now have access to a fx:user URI which allows us to view and alter the user record we just created, and the fx:stores URI which we'll be using now to create a new store connected to this user. Submit a POST request to the fx:stores link relationship, posting the necessary details as described in the API Reference. At a minimum, the store_name, store_domain, store_url, store_email, postal_code, region and country parameters are required.
If successful, as with the Foxy User creation, you’ll receive the access_token and refresh_token with the store_full_access scope. Again, these will need to be stored securely so you can use them in the future to access this store with the API.
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer b4h50ShRPJ2967DWK6h20shyYWMP920dUEBnric5" https://api.foxycart.com/users/46000/stores -d "store_name=Johns+Test+Store&store_domain=johnsteststore&store_url=http://www.example.com&store_email=orders@example.com&postal_code=77018®ion=TX&country=US"
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:attributes": {
"href": "https://api.foxycart.com/stores/41000/attributes",
"title": "Attributes for This Store"
},
"fx:store_version": {
"href": "https://api.foxycart.com/property_helpers/store_versions/24",
"title": "This store version"
},
"fx:users": {
"href": "https://api.foxycart.com/stores/41000/users",
"title": "Users for This Store"
},
"fx:user_accesses": {
"href": "https://api.foxycart.com/stores/41000/user_accesses",
"title": "User Access for This Store"
},
"fx:customers": {
"href": "https://api.foxycart.com/stores/41000/customers",
"title": "Customers for This Store"
},
"fx:carts": {
"href": "https://api.foxycart.com/stores/41000/carts",
"title": "Carts for This Store"
},
"fx:transactions": {
"href": "https://api.foxycart.com/stores/41000/transactions",
"title": "Transactions for This Store"
},
"fx:subscriptions": {
"href": "https://api.foxycart.com/stores/41000/subscriptions",
"title": "Subscriptions for This Store"
},
"fx:subscription_settings": {
"href": "https://api.foxycart.com/store_subscription_settings/41000",
"title": "Subscription Settings for This Store"
},
"fx:process_subscription_webhook": {
"href": "https://api.foxycart.com/stores/41000/process_subscription_webhook",
"title": "POST here to resend the daily subscription webhook notification for this store"
},
"fx:item_categories": {
"href": "https://api.foxycart.com/stores/41000/item_categories",
"title": "Item Categories for This Store"
},
"fx:taxes": {
"href": "https://api.foxycart.com/stores/41000/taxes",
"title": "Taxes for This Store"
},
"fx:payment_method_sets": {
"href": "https://api.foxycart.com/stores/41000/payment_method_sets",
"title": "Payment Method Sets for This Store"
},
"fx:coupons": {
"href": "https://api.foxycart.com/stores/41000/coupons",
"title": "Coupons for This Store"
},
"fx:template_sets": {
"href": "https://api.foxycart.com/stores/41000/template_sets",
"title": "Template Sets for This Store"
},
"fx:cart_templates": {
"href": "https://api.foxycart.com/stores/41000/cart_templates",
"title": "Cart Templates for This Store"
},
"fx:cart_include_templates": {
"href": "https://api.foxycart.com/stores/41000/cart_include_templates",
"title": "Cart Include Templates for This Store"
},
"fx:checkout_templates": {
"href": "https://api.foxycart.com/stores/41000/checkout_templates",
"title": "Checkout Templates for This Store"
},
"fx:receipt_templates": {
"href": "https://api.foxycart.com/stores/41000/receipt_templates",
"title": "Receipt Templates for This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/41000/email_templates",
"title": "Email Templates for This Store"
},
"fx:error_entries": {
"href": "https://api.foxycart.com/stores/41000/error_entries",
"title": "Error Entries for This Store"
},
"fx:downloadables": {
"href": "https://api.foxycart.com/stores/41000/downloadables",
"title": "Downloadables for This Store"
},
"fx:payment_gateways": {
"href": "https://api.foxycart.com/stores/41000/payment_gateways",
"title": "Payment Gateways for This Store"
},
"fx:hosted_payment_gateways": {
"href": "https://api.foxycart.com/stores/41000/hosted_payment_gateways",
"title": "Hosted Payment Gateways for This Store"
},
"fx:fraud_protections": {
"href": "https://api.foxycart.com/stores/41000/fraud_protections",
"title": "Fraud Protections for This Store"
},
"fx:payment_methods_expiring": {
"href": "https://api.foxycart.com/stores/41000/payment_methods_expiring",
"title": "Customer payment methods which are about to expire"
},
"fx:store_shipping_methods": {
"href": "https://api.foxycart.com/stores/41000/store_shipping_methods",
"title": "Shipping methods supported by this store"
},
"fx:integrations": {
"href": "https://api.foxycart.com/stores/41000/integrations",
"title": "Third party integrations which have been granted OAuth access to this store"
},
"fx:native_integrations": {
"href": "https://api.foxycart.com/stores/41000/native_integrations",
"title": "Third party integrations which require credentials and configuration."
},
"fx:activate_store_monthly_url": {
"href": "https://signup.foxycart.com/cart?cart=checkout&empty=true&quantity_max=1||aac2bf494642ffae80e49a4e366bfbbcb3cd605d879e9e44d3dda4b28f525968&name=FoxyCart.com+Store+Subscription||97e725112618487b4387b330c088264eb7c7e8801e073d2814ab1cdf419ff261&price=20||fef519dbd677209fa353add140c5a4c32f7a7bf5fecfcf8ae4bf76c3ddb2913e&sub_frequency=1m||3801ed11fdaca67966910977bc6f9916a9808c01e028b94c081e874c4a0e5bd2&code=41000||b75f98a4d6fc071a640d8ccab812159774b82bcd9bf5464046bb85201c0ee3a7&user_id=46000||336d0c8abf29a52897837c8d75038a361b48cd19db5802e9a38d31f880d467ef&Store_Name=Johns+Test+Store||351d0cf07a11570dff26391c8635ef0d04a5d7ed21aa91de836f72e27ec62b7d&plan=standard||9e0b048b50af410610bd1e27467a29cb0c0acac499cc7b9d82fe55faa79a5557",
"title": "Follow this link in your browser to pay for your monthly subscription and activate this store",
"type": "text/html"
},
"fx:activate_store_yearly_url": {
"href": "https://signup.foxycart.com/cart?cart=checkout&empty=true&quantity_max=1||aac2bf494642ffae80e49a4e366bfbbcb3cd605d879e9e44d3dda4b28f525968&name=FoxyCart.com+Store+Subscription||97e725112618487b4387b330c088264eb7c7e8801e073d2814ab1cdf419ff261&price=180||8e2aab3925fb08dc12aff39e4fc00d9b8485fe34fac4fffc5cf9fed06ab43be0&sub_frequency=1y||bb1657f50364db6c64441c4f128223ec79f423c478290ba2928ef53432042308&code=41000||b75f98a4d6fc071a640d8ccab812159774b82bcd9bf5464046bb85201c0ee3a7&user_id=46000||336d0c8abf29a52897837c8d75038a361b48cd19db5802e9a38d31f880d467ef&Store_Name=Johns+Test+Store||351d0cf07a11570dff26391c8635ef0d04a5d7ed21aa91de836f72e27ec62b7d&plan=standard||9e0b048b50af410610bd1e27467a29cb0c0acac499cc7b9d82fe55faa79a5557",
"title": "Follow this link in your browser to pay for your yearly subscription and activate this store",
"type": "text/html"
}
},
"message": "store 41000 created successfully.",
"token": {
"access_token": "a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f",
"expires_in": 7200,
"token_type": "Bearer",
"scope": "store_id_41000 store_full_access",
"refresh_token": "842k4hd083JDO602HMdiJ583HnhOdna38pQmd544"
}
}Authenticating API Calls
With the Access token in hand, your application can 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 76e9237hHosdp4890sjjafu38U78HJSund7295a9For more details on working with the API, see the API Reference.
Refreshing the Access Token
As the Access Token expires after 2 hours, if your integration needs to access the protected resource beyond that point, you’ll need to use the corresponding refresh_token and the fx:token endpoint of the API to request a new access_token. Review the Refreshing the Access Token page for details on doing that.