Securely Storing OAuth Tokens

When working with the Foxy Hypermedia API, you will be handling different credentials and tokens provided to you by Foxy that can grant access to your users Foxy user and store accounts. As such, special care should be taken when handling these values.

Client ID

The Client ID is the public identifier for your OAuth Client, and as such is not sensitive. As the Client ID alone can not be used to access anything without also having other sensitive values, it can be openly referenced in code or referenced in email to Foxy support.

Client Secret

The Client Secret should be handled with care, and treated like the master password for your OAuth Client. As such, it should be stored securely and encrypted. It should never be included in public code repositories, client side javascript or in emails.

If your Client Secret is ever compromised - then it’s possible that your whole OAuth Client could be compromised. A new OAuth Client would then need to be created and your users would need to re-authenticate with your application.

Access and Refresh Tokens

The tokens provide access to protected resources, as dictated by their scope, and as such should be handled with care. They should be never placed in public code repositories, client side javascript or in emails.

The Access Token acts like a user’s authenticated session, and in the case of a store_full_access scope provides access to all areas of a store. As it is only valid for 2 hours the Access Token doesn't need to be stored long term - sessions can be a good way to store them while active.

The Refresh Token, when paired with the Client ID and Secret can be used to generate a new Access Token. It should be securely stored and encrypted.

Environment Variable vs Database Storage

If possible, store any of the sensitive values as environment variables for your application. This keeps them completely separate from your code base and database.

If you dynamically receive sensitive values within your application (such as a user granting access to their store), you will need to store that value in your database. In that case, we strongly recommend encrypting these values prior to storage, with the encryption key stored in the environment variables.

Redirect URI

The Redirect URI setting is a publicly accessible URL, so it’s not sensitive. It should be for a domain that is within your control though.

For requests sent to your Redirect URI as part of the OAuth flow, the state parameter as you provided it in your initial request will be included in the response. We strongly recommend first confirming that the returned value matches what you sent in order to confirm that the request is valid.

SSL Certificates

While not required, we strongly recommend that your application be secured with an SSL Certificate. When connecting to our API over https, we also recommend wherever possible validating our SSL Certificate. If you’re using a library, this may already be enabled by default, but you should confirm this to ensure it is. If you see any settings to “verify SSL”, ensure that it is set to true.

Recovering From Compromised OAuth Credentials

If you are ever in a situation where you believe that any of your OAuth credentials are compromised, it's important that you quickly update and replace any affected credentials across your application.

Change The Client Secret

As the Client Secret is utilised when generating new Access Tokens from the Refresh Token, by updating it you ensure that any attempts to generate Access Tokens using the old Secret after that will no longer work. Any Access Tokens created prior to changing the Client Secret will still remain active until their 2 hour validity passes.

To update a Client Secret, you will need to perform a PATCH request to the fx:client endpoint using your client_full_access scoped Access Token, passing a new client_secret value. Alternatively, you can pass a blank client_secret value, and a new random secret will be generated for you in the response. Refer to the Creating an OAuth Client page for details on working with the client.

Once you have a new Client Secret created, you can then update the value within your application - ensuring that you're storing it securely as noted above.