OAuth2.0 Authorization Code Flow

In order to call endpoints on behalf of users, users need to authorize your App. Awardable uses the OAuth2.0 standard flow for this.

     +--------+                               +---------------+
     |        |--(A)- Authorization Request ->|   Resource    |
     |        |                               |     Owner     |
     |        |<-(B)-- Authorization Grant ---|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(C)-- Authorization Grant -->| Authorization |
     | Client |                               |     Server    |
     |        |<-(D)----- Access Token -------|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(E)----- Access Token ------>|    Resource   |
     |        |                               |     Server    |
     |        |<-(F)--- Protected Resource ---|               |
     +--------+                               +---------------+

Figure from The OAuth 2.0 Authorization Framework

Authorization Request

You need to build an authorize URL to AWRD, specifying which scopes your App requires, your App Id, and the URL toward which the user will be redirected after they approved your request. For example:

{{AWRD_URL}}?client_id=12345678&redirect_uri=https://www.example.com&scope=badge.create,badge.edit,badge.claim,offline

@Untitled needs to replace {{AWRD_URL}}

The each scope required must be separated by a comma , in the list. The redirect URL needs to be registered in your App settings on the App configuration page.

If the user approve the request, they will be redirect to the specified URL, with the Authorization Grand code as parameter. For example:

https://www.example.com?code=DLDqeQfVG4rTGmCib8dIik4Op04mA2

Authorization Grant token exchange

Thereafter, your App’s backend needs to exchange the Grant code to an Access token. In order to do so, you need to call the following endpoint: https://{{AWRD_API_URL}}/v1/oauth/token

This is a POST endpoint, which require a payload similar to:

{
	"grant_type": "authorization_code",
	"redirect_uri": "https://www.example.com",
	"authorization_code": "DLDqeQfVG4rTGmCib8dIik4Op04mA2"
}

You need to authenticate your App by using its Bearer token in the header, as explained in Authentication.

If valid, the endpoint will return a response similar to:

{
  "statusCode": 200,
  "access_token": "MTIzOjhYNVRuYmtyaURXekZoa09nUzM2Njg5WGxuWVFQdnE3NmhQSVc1Tjc=",
  "token_type": "Authorization",
  "expires_in": 900,
  "refresh_token": "MTIzOmxlcGw4VTM2c1RlUUE1U1ZsZ3BPZGc2U1NYakMyR0FySXQ0eU5wa08=",
  "scope": [
	  "badge.create",
	  "badge.edit",
	  "badge.claim",
	  "offline"
  ]
}

This Authorization token can then be used to make authenticate calls on behalf of the users, as explained in Authentication. Note: if the offline scope is not required, the refresh_token will be empty.

💡

Access, Bearer, or Refresh tokens are as sensitive as passwords, they need to be protected and should not be shared or distributed to untrusted parties. If your App is found leaking user tokens, your access will be revoked.

Refresh token

If the offline scope is required, a refresh token is provided. This token can be used to generate a new access token after the previous one expired. Note that are fresh token can be used only once, a new refresh token will be provided when you use one. A refresh token expires after one year if not used.

In order to use the refresh token, you need to call again the following endpoint: https://{{AWRD_API_URL}}/v1/oauth/token

The payload is then similar to:

{
	"grant_type": "refresh_token",
	"refresh_token": "MTIzOmxlcGw4VTM2c1RlUUE1U1ZsZ3BPZGc2U1NYakMyR0FySXQ0eU5wa08="
}

If valid, the endpoint will return a response similar to:

{
  "statusCode": 200,
  "access_token": "MTIzOjhYNVRuYmtyaURXekZoa09nUzM2Njg5WGxuWVFQdnE3NmhQSVc1Tjc=",
  "token_type": "Authorization",
  "expires_in": 900,
  "refresh_token": "MTIzOmxlcGw4VTM2c1RlUUE1U1ZsZ3BPZGc2U1NYakMyR0FySXQ0eU5wa08=",
  "scope": [
	  "badge.create",
	  "badge.edit",
	  "badge.claim",
	  "offline"
  ]
}