How to set up the OAuth flow for your app in Judge.me

Judge.me uses OAuth to grant App Developers access to Judge.me API. Essentially, OAuth is a mechanism that allows App Developers to ask Shops to grant predefined access to develop Apps via an API token so that App Developers can make authenticated requests to Judge.me API on the behavior of the Shops.

In this guide, we'll show you how to set up the OAuth flow in Judge.me.

TABLE OF CONTENTS

1. Create an app in Judge.me
2. Identify the scopes
3. Request an authorization code
4. Exchange for a permanent access token

1. Create an app in Judge.me

• Go to judge.me/login and enter the email address to log in as a reviewer.

• Judge.me will send a "magic link" to your email, follow the link to continue the login process.

• After you are logged in, follow this link to create a new app: https://judge.me/profile/apps/new
• Fill in the required fields, then click Create.
  1. App Name: your app name
  2. Redirect URI: the endpoint that Judge.me will use to send authorization confirmation with the authorization code back to your App server (e.g. https://example.com/auth/judgeme/callback).
  3. Logo URL: a direct link to your app logo
  4. Link to: link to your app homepage

• After your app is created, click the "edit" icon and you can see the Client ID and Secret. You can use these values to make an authorization request and exchange for an access token later.

2. Identify the scopes

Scopes enable your app to only request access to the necessary data and let shops control the number of permissions they grant to your app. Therefore, make sure to request only the relevant scopes so you are more likely to get approval from the shops. Here is the full list of scopes that you might use to access Judge.me API. Make sure you use the correct names of the scopes.

3.  Build the authorization URL to redirect shops to Judge.me

• Judge.me OAuth uses OAuth 2.0 standard so you can refer to any OAuth 2.0 guide.
• You need to build an authorization URL to redirect the shops to Judge.me. This URL includes parameters that identify your app and define the permissions (scopes) that the shops are asked to grant your app.
• When the shops click on the authorization URL, your app redirects the shops to Judge.me. The authorization URL loads the OAuth grant screen and requests the shops to authorize the scopes you are asking for.

• When the shops agree to grant permissions, the authorization request is sent to Judge.me, and Judge.me will respond to the Redirect URI you provided with the authorization code. Your app has to listen to this Redirect URI to receive this code.

Format of an authorization URL:

method=GET https://judge.me/oauth/authorize?client_id=[your_client_id]&redirect_uri=[your_redirect_uri]&response_type=code&scope=[list_of_permissions_you_are_asking]&state=[state]

Example of a real authorization URL:

method=GET https://judge.me/oauth/authorize?client_id=e9aa17df97285cc93373ec809806c55452280b840985814d30b9fc71c3016252&redirect_uri=https://example_app.com/oauth_callback&response_type=code&scope=read_products%20write_products&state=806c55452280b840985814d30b9fc

Parameters in the authorization URL:

Example of a callback from Judge.me with an authorization code to your app:

Started GET "https://example.com/auth/judgeme/callback?code=32279746ee4db4312ca49ae627f043fbc3680f605c3603170e5a875f7afe2b1c"

4. Exchange for a permanent access token

Next, you need to exchange the authorization code for a permanent access token. This access token lets you call relevant APIs within your defined scopes.

To exchange the access token, you'll need:

• client_id (from step 1)
• client_secret (from step 1)
• code (from step 3)
• redirect_uri (link to your app server)

The client_id and client_secret are what you have got from step 1 when creating an app. The code is what you get from step 3. The redirect_uri is the link to your app server.

curl --location --request POST 'https://judge.me/oauth/token' \--header 'Content-Type: application/json' \--data-raw '{ "client_id": "7ce4d77492c0ab540885601378e7442415b14e48b9865ab1bf5a9d548fa8eba8", "client_secret": "5f62a03e9ff7349b57aaade0b8d78f7603256bd97a347f6949424c1ade4383a2", "code": "32279746ee4db4312ca49ae627f043fbc3680f605c3603170e5a875f7afe2b1c", "redirect_uri": "http://example.com/auth/judgeme/callback", "state": "9f1c39b9a714771ccb331fb5742a57453fae7173a26329d0", "grant_type": "authorization_code"}'

Here is an example of a response from Judge.me:

{ "access_token": "39452ed283252c8ea2083faa9b371cc77e82c22471da921b8cd6db935e4ee37a", "token_type": "Bearer", "scope": "read_products write_products public", "created_at": 1646287086}

With this access token, you can call relevant APIs from Judge.me:

curl --location --request GET 'https://judge.me/api/v1/products' \--header 'Content-Type: application/json' \--data-raw '{"api_token": "39452ed283252c8ea2083faa9b371cc77e82c22471da921b8cd6db935e4ee37a"}'

If you call APIs defined previously in your scope, you'll get access to the relevant data. For example, if you call read_products (in your scope), you will get the product information.

If you call APIs not defined previously, you'll get an error. For example, if you call read_reviews (not in your scope), you'll get an error: "You don't have access to the resource".

curl --location --request GET 'https://judge.me/api/v1/reviews' \--header 'Content-Type: application/json' \--data-raw '{"api_token": "39452ed283252c8ea2083faa9b371cc77e82c22471da921b8cd6db935e4ee37a"}'{ "error": "You don't have access to the resource"}