App Authentication (OAuth)

📘

App OAuth authentication is for Fera Partners to create app integrations with the Fera platform. If you're not a partner, you should use API Key Authentication instead.

Fera Apps use the OAuth2 authentication protocol with the following attributes:

• Authorization URL is https://app.fera.ai/oauth/authorize.
• Token URL is https://app.fera.ai/oauth/token.
• Token revocation URL is https://app.fera.ai/oauth/revoke. (see Revoke App Authentication)

Once you receive an access token (AKA "auth_token") you can access the API by including your auth token as the Authorization "Bearer" header.

App Setup

To get started, log into the Fera Partner Portal and create a new app.

Once you've created your app you'll get a Client ID and Client Secret. Use those keys to follow a standard OAuth2 flow.

🚧

Never give out your Client Secret.

Your Client Secret is used to encrypt communications and data between your server and Fera's server. Keep it hidden, out of your code base and never reveal it to anyone outside your organization.

Example OAuth2 Flow

1. Authorize

curl 'https://app.fera.ai/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&scope=read+write&redirect_uri=YOUR_APP_REDIRECT_URI&state=SOME_RANDOM_STRING'

auth_request = HTTParty.get("https://app.fera.ai/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&scope=read+write&redirect_uri=YOUR_APP_REDIRECT_URI&state=SOME_RANDOM_STRING")

Authorization Parameters:

• client_id*: The Client ID that you had got from the developer portal.
• scope*: "permissions" the app requires for completing the authorization flow. More about this in OAuth2 Scopes. Valid scopes are: read and write.
• redirect_uri*: Where to redirect (on the app's back-end) after the app is authorized in order to get the tokens. This must match what you configured in the app settings
• state*: Random string, protecting against CSRF attacks.
• store: (optional) Store domain or ID you want to authorize. Example: megans-cupcakes.myshopify.com

If done properly this will redirect the user to a page that looks like this:

2. Access/Auth Token

If the user clicks the authorize button they'll be sent to your redirect URI with the following parameters in the URL:

• code: You'll use this to generate the access token
• state: It's your job to verify that this matches the state variable you set in the initial authorization request.

Now it's time to request an auth token:

curl -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET -X POST https://app.fera.ai/oauth/token \
  -d grant_type=authorization_code \
  -d redirect_uri="YOUR_REDIRCT_URI" \
  -d code=THE_CODE_YOU_GOT_IN_PREVIOUS_STEP

You'll get a response that looks like this:

{
    "access_token":"YOUR_AUTH_TOKEN",
    "scope":"read write",
    "token_type":"Bearer"
}

Now just save that YOUR_AUTH_TOKEN because you're done the hard part!

👍

No refresh token needed

Auth tokens don't expire so there is no refresh token. We decided to go for "simplicity" by omitting this step, but it means we're trusting you to keep the auth token safe and secure!

3. Test API Request

Use the YOUR_AUTH_TOKEN value you got in the previous step like this to make requests to the API:

curl --request GET --url https://api.fera.ai/v3/private/reviews  --header 'Authorization: Bearer YOUR_AUTH_TOKEN'

📘

You can skip these steps for Fera accounts/stores you manage by using the Test Install feature.