client

Description

To view and work with a client, you must be connected to the API using an OAuth token with client_full_access scope.

Creating a Client resource is how you register your client application with our API as described in the OAuth 2.0 RFC. It is the first required step for working with the Foxy API. When you register your client, you'll receive an OAuth 2.0 access_token and refresh_token in the response with a client_full_access scope. You'll use these tokens any time you want to view or modify your client registration. The response will also include your client_id and client_secret which you'll need for refreshing your access tokens.

After you connect to the API with your client token, you'll then be able to access your client_id and client_secret which your application will need to interact with the Foxy API's OAuth 2.0 system. The client_secret must be stored securely (preferably encrypted) and should never be stored publicly, such as in a public repo or publicly accessible database.

If your client application is a software as a service, you will only need one client for your application. If your client software, on the other hand, will be distributed for others to download and host themselves, your application will have to talk to the API to create a Client resource and register each installation. See the Getting Started documentation for more information.

Once you create a client and connect with the client_full_access scope, you can then create a user or connect to an existing user using the user_full_accessOAuth scope. Once connected to the API using an OAuth token with the user_full_access scope, you can create a store or connect to an existing store with the store_full_acesss scope.

If you create custom attributes for a client, they will automatically be included in the response as embedded resources without having to zoom in on them.

When creating a client resource, the response will include the OAuth Access and Refresh tokens required to work with this resource via the API. It's important to save this information in your database. If you lose it, you'll have to do an OAuth Authorization Code grant via your browser. We also include the client_id and client_secret which are needed to refresh your access tokens and work with OAuth 2.0.

Actions

POST
Create a new client
OPTIONS
Get a response explaining which HTTP methods are supported

Properties

Property Description Type Constraints
client_id A unique identifier for this client. If you do not supply one, one will be automatically generated for you. If you're not hosting the client integration yourself, please use a known prefix when creating your clients. This can not be modified once it is created. String Unique. Can only be set on creation. Between 15 and 200 characters.
client_secret The password to be used with this client_id for OAuth 2.0 integration. This is generated automatically and can't be changed. String Required, random value set if blank
redirect_uri This is the redirection endpoint as described by OAuth 2.0 URL Required. 200 characters or less.
project_name The name of this project which will be using the API. This should be specific to the installation and implementation of this client. This information will be displayed on your OAuth 2.0 authentication page. String Required. 100 characters or less.
project_description A description of this project. This information will be displayed on your OAuth 2.0 authentication page. String 200 characters or less.
company_name The name of the company responsible for this project. This information will be displayed on your OAuth 2.0 authentication page. String Required. 100 characters or less.
company_url The name of the company responsible for this project. This information will be displayed on your OAuth 2.0 authentication page. URL 200 characters or less.
company_logo An image url for this company. This information will be displayed on your OAuth 2.0 authentication page. URL 200 characters or less.
contact_name The individual responsible for this integration. String Required. 100 characters or less.
contact_email The email address of the individual responsible for this integration. String Required. 100 characters or less.
contact_phone The phone number of the individual responsible for this integration. String Required. 100 characters or less.
date_created The date this resource was created. Date Read only
date_modified The date this resource was last modified. Date Read only

Example Representation

{
    "_links": {
        "curies": [
            {
                "name": "fx",
                "href": "https://api.foxycart.com/rels/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://api.foxycart.com/clients/42",
            "title": "Example Project"
        },
        "fx:attributes": {
            "href": "https://api.foxycart.com/clients/42/attributes",
            "title": "Attributes for This Client"
        }
    },
    "client_id": "client_JnVvPWxBz4Ep7YcpJFeU",
    "client_secret": "7dn2cmvUS5btm1S6Mfygd7vaVBuv7Cf8Fx1HKqsx",
    "redirect_uri": "http://example.com",
    "javascript_origin_uri": "",
    "project_name": "Example Project",
    "project_description": "A really cool project using the API to make awesome. Lots and lots of awesome. Oh, and money too. People like money.",
    "company_name": "Super amazing company",
    "company_url": "http://example.com",
    "company_logo": "",
    "contact_name": "John Doe",
    "contact_email": "john.doe@example.com",
    "contact_phone": "555-555-5555"
}

Response from POST:

{
    "_links": {
        "curies": [
            {
                "name": "fx",
                "href": "https://api.foxycart.com/rels/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://api.foxycart.com/clients/44",
            "title": "This Client"
        },
        "fx:attributes": {
            "href": "https://api.foxycart.com/clients/44/attributes",
            "title": "Attributes for This User"
        }
    },
    {
      "message": "client 44 created successfully.",
      "token": {
        "access_token": "590a79faf06e4062cabf2ec866a6c121065417fc",
        "expires_in": 7200,
        "token_type": "bearer",
        "scope": "client_full_access",
        "refresh_token": "3ea1c2d62826cddce440ceaa0d69c9b396ee394a"
      },
      "client_id": "client_d83ALxkMRDingytReh4C",
      "client_secret": "itt3U2biSMlVQiqsFF9sdlFjJZ1T7UlghId2Been"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api.foxycart.com/clients/42" rel="https://api.foxycart.com/rels/client">
  <link rel="self" href="https://api.foxycart.com/clients/42" title="Example Project"/>
  <link rel="https://api.foxycart.com/rels/attributes" href="https://api.foxycart.com/clients/42/attributes" title="Attributes for This Client"/>
  <client_id>client_JnVvPWxBz4Ep7YcpJFeU</client_id>
  <client_secret>7dn2cmvUS5btm1S6Mfygd7vaVBuv7Cf8Fx1HKqsx</client_secret>
  <redirect_uri>http://example.com</redirect_uri>
  <javascript_origin_uri></javascript_origin_uri>
  <project_name>Example Project</project_name>
  <project_description>A really cool project using the API to make awesome. Lots and lots of awesome. Oh, and money too. People like money.</project_description>
  <company_name>Super amazing company</company_name>
  <company_url>http://example.com</company_url>
  <company_logo></company_logo>
  <contact_name>John Doe</contact_name>
  <contact_email>john.doe@example.com</contact_email>
  <contact_phone>555-555-5555</contact_phone>
</resource>

Response from POST:

<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api.foxycart.com/clients/44">
  <link rel="self" href="https://api.foxycart.com/clients/44" title="This Client"/>
  <link rel="https://api.foxycart.com/rels/attributes" href="https://api.foxycart.com/clients/44/attributes" title="Attributes for This Client"/>
  <message>client 44 created successfully.</message>
  <token>
    <access_token>590a79faf06e4062cabf2ec866a6c121065417fc</access_token>
    <expires_in>7200</expires_in>
    <token_type>bearer</token_type>
    <scope>client_full_access</scope>
    <refresh_token>3ea1c2d62826cddce440ceaa0d69c9b396ee394a</refresh_token>
  </token>
  <client_id>client_d83ALxkMRDingytReh4C</client_id>
  <client_secret>itt3U2biSMlVQiqsFF9sdlFjJZ1T7UlghId2Been</client_secret>
</resource>

{
    "class": [
        "client"
    ],
    "properties": {
        "client_id": "client_JnVvPWxBz4Ep7YcpJFeU",
        "client_secret": "7dn2cmvUS5btm1S6Mfygd7vaVBuv7Cf8Fx1HKqsx",
        "redirect_uri": "http://example.com",
        "javascript_origin_uri": "",
        "project_name": "Example Project",
        "project_description": "A really cool project using the API to make awesome. Lots and lots of awesome. Oh, and money too. People like money.",
        "company_name": "Super amazing company",
        "company_url": "http://example.com",
        "company_logo": "",
        "contact_name": "John Doe",
        "contact_email": "john.doe@example.com",
        "contact_phone": "555-555-5555"
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "https://api.foxycart.com/clients/42"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/attributes"
            ],
            "href": "https://api.foxycart.com/clients/42/attributes"
        }
    ]
}

Response from POST:

{
    "properties": {
        "message": "client 44 created successfully.",
        "token": {
            "access_token": "590a79faf06e4062cabf2ec866a6c121065417fc",
            "expires_in": 7200,
            "token_type": "bearer",
            "scope": "client_full_access",
            "refresh_token": "3ea1c2d62826cddce440ceaa0d69c9b396ee394a"
        },
        "client_id": "client_d83ALxkMRDingytReh4C",
        "client_secret": "itt3U2biSMlVQiqsFF9sdlFjJZ1T7UlghId2Been"
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "https://api.foxycart.com/clients/44"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/attributes"
            ],
            "href": "https://api.foxycart.com/clients/44/attributes"
        }
    ]
}

Zoomable Resources

This resource has no linked resources which can be "zoomed" in on, filtered and embedded within this resource.