OAuth is an open-standard authorisation protocol or framework that describes how unrelated servers and services can safely allow authenticated access to their assets without actually sharing the initial, related, single logon credential.
As OAuth is an open source protocol/framework and not a service or provider it self, it can be used by a number of service providers to provide authorisation and authentication services. For example, products like Auth0, RIVT built their own API sweet on top of the OAuth protocol.
Important Note: If your provider is Auth0, please use our pre build Auth0 integration. Lear more here.
As different providers provide their own solution and API to work with the OAuth protocol, it becomes very difficult to build one solution that caters them all. Therefore, Apps Creator's OAuth Integration is a versatile tool that can help you map various API endpoints to make a custom solution for your OAuth provider.
Prerequisites:
1. The following process requires Mid-Advance level of technical knowledge and understanding of APIs and how they work.
2. Complete API documentation from your OAuth Provider is required for correct mapping of each end point.
Add OAuth Integration to your Apps Creator Account
Step 1: Login to Apps Creator Dashboard
Step 2: Navigate to Manage >> Integration and click on the "+" icon.
Step 3: From the menu select OAuth to add it to your Apps Creator account.
How to Configure the OAuth Integration
Depending on your OAuth Authentication/Authorisation provider the steps below will differ. For this article we are using a hypothetical provider and their API documentation. These steps will guide you on how to use the OAuth Integration tool in Apps Creator to configure the OAuth integration based on your provider's API documentation.
Settings Section
Under this section you will add the Client ID and Secret provided by your provider. You can leave the scope as "openid profile email" unless your provider asks to setup a different scope.
Authorisation Type - Code Grant or Password Grant
Your provider may support both Code and Password grant authorisation type or they may support only one of these. Depending on your provider please choose one by toggling that type on, in the OAuth Integration form. By default, code grant is turned on.
Important Note: Code Grant is not supported on Roku Platform.
As an example, we will configure the Password Grant Authorisation in this article.
Password Grant - Registration URL
This is the URL of the API end point which will be used to register a new user in your provider's database, when a user creates a new account from within the Apps Creator Apps.
Find such an end point from your provider's API documentation and enter it here.
Password Grant - Registration Headers and Body
Headers and Body will be used to provide the data to your provider when the apps will make a request to the registration URL. You can configure these adding the required elements in the JSON editor, under Registration Headers and Body.
As an example, let's take a look at our dummy Registration endpoint. To register a new user in our dummy provider, we need to make a request at https://prod-api.dummyprovider.com/auth/login/. In this request we need to add the following headers:
{
"Api-Key": "myapikey",
"Content-Type": "application/json"
}
And, in body we need to send the new user's email and the password:
{
"email": "example@example.com",
"password": "mypassword"
}
To add these in our Registration form we will use the JSON editor. Click on the small box icon to append a new field, from the list select "string". This will add a new key value pair, that will accept a string value. You can all as many Key value pairs as your provider needs.
After adding the values as per our dummy API provider, the resulting Headers and Body will look like this:
If you notice the Body section in the above image, you will see that we have used some placeholders for the email and password values. These placeholders will be replaced by the email and password entered by the user during runtime. You can find the complete list of usable placeholders at the end of this article.
Apart from Header and Body, you also need to specify the Request Method. depending on your API endpoint you can choose from: POST, GET, PUT, PATCH ,& DELETE.
Password Grant - Token Endpoint
The Token end point is used when a user tries to log into the apps. This end point provides us with the user authentication token on a successful login attempt.
Similar to our registration end point, we will now configure our Token URL, Header, Body and Method. Enter the Token end point URL as per your provider and configure the Headers and Method depending on your end point's specifications.
For Body, you will notice that we have pre-populated some fields. Your provider may not need all of them. Therefore, configure the Body section as per your end-point's requirements.
In our dummy provider example, we only need to send the email and password of the user. So, our setup will look as shown in the below image.
Reset Password Endpoint
This end point is used when a user hits Forgot Password button in the Apps. This will send a request to your provider to send the password reset email to the clients registered email.
Similar to the registration endpoint, please configure this as per your provider's documentation.
Below is an example based on our dummy API.
Authenticated APIs
Authenticated APIs are used once the user is successfully logged into the App. These APIs are used to fetch user details, entitlements etc.
Under this section you will find the option to configure three different endpoints:
1. Profile
If your provider provides an end-point to fetch the user account details, you can configure this endpoint. We will use this to fetch the member ID/Client ID from your database provider to store in our Database.
2. List Entitlement
This API is used to get all the entitlements for a specific authenticated user.
3. Update Entitlement
Apps creator can not only receive information from your provider's database, but we can also sent entitlement information to your provider. This is useful, if you want to update a user's record with the entitlement that they purchased in the Apps Creator apps.
Your provider may send the profile and entitlement information using the same end point, in that case you can configure the same end point under both profile and list entitlement section.
For example, in our dummy provider's case, both the user information and entitlement information is sent in one API call to this end point: https://prod-api.dummyprovider.com/user/profile/
Therefore, we will configure our profile and list entitlement section as shown below.
Authenticated API- Update Entitlement
Update Entitlement API end-point is used to update the entitlement information of pre-registered user in your database. Apps Creator can send new entitlement information to your provider, whenever an entitlement is purchased or renewed in the app. It can be configured in the similar way as we configured rest of the sections in the integration.
Below is an example based on our dummy provider:
In the above example, we are making a call at the following URL: https://prod- api.dummyprovider.com/user/profile/mazdata/?uuid={{member_id}}
Notice that we can use the placeholders in the URLs as well. Therefore, we are sending the member_id in the uuid key, directly inside the URL.
In the Body, we are sending the start and end date of the new entitlement. There are a number of placeholders that can be used and are described in detail at the end of this article.
Advance Section - Policy
Policy is a crucial part when using the Authenticated APIs. As different providers can use different JSON structure to send the data in the response, we need a way to map our internal parameters to the parameters sent by your provider. By configuring the policy correctly, we will know which parameter in your provider's response maps to the member ID, start date, end date, account status etc.
Below is an example from our dummy provider:
In the above example, we have configured the Policy based on the following response from the Profile API end point:
{
"uuid": "b2aed540-c550-45e3-a92f-qdfadfdf",
"first_name": "",
"last_name": "",
"email": "vijay.sharma+outside@backlight.co",
"avatar_url": "",
"gender": "",
"country_code": "",
"state_code": "",
"zip_code": "",
"system_lists": {
"history": "b9bf7d8e-bc10-4746-af06-718e56e2656f",
"favorites": "49b7a9fd-77bf-453a-b022-c5889bdee13f",
"liked": "4fd6a203-9ba6-4e2e-96ff-684f88c853d2",
"disliked": "0e0d73cb-e4ac-4142-bb67-dde10321fbac",
"saved_for_later": "672b61cf-0a98-4189-95e8-39b61a446e46"
},
"membership": {
"ad_free": false,
"subscription": null,
"recurring_payment_source_property": "rivt",
"oplus_subscription_migrated_from_name": null,
"expires_at": null,
"true_expires_at": null,
"membership_type": "free_membership",
"true_membership_type": "free_membership",
"created_at": "2023-02-27T13:07:50.230670Z",
"updated_at": "2023-02-27T13:07:50.236098Z",
"canceled_at": null,
"paid_up_until": null,
"uuid": "1a1b3281-7f07-4c60-9aff-718e56e2656f",
"stripe_subscription_status": null,
},
"newsletter_subscribed": false,
"email_confirmed": false,
"signup_source": "Database",
"exclude_from_analytics": false,
"tos_accepted": true,
"activated": true,
"member_exclusive_level": "registered_access",
"is_employee": false
}
There are a lot of parameters that can be configured using the policy configurator. A complete list of these parameters can be found at the end of this article.
Important Note:
The configuration shown in this article is just an example. Based on your provider, you can configure each and every end point.
In case you are unable to find the parameters required to configure your provider in the below list please reach out to us on appsupport@zype.com. Please add your provider's API documentation in your support request.
Supported Parameters
| S. No | Parameter Name | Description |
| 1 |
target_email |
To map the customer email received from the Profile API. |
| 2 |
target_member_id |
To map the unique customer id received from the Profile API. |
| 3 |
target_access_token |
Access token received from Profile or Entitlement API End points |
| 4 |
target_refresh_token |
Refresh token received from Profile or Entitlement API End points |
| 5 |
target_token_type |
Type of token. Ex. Bearer |
| 6 |
target_expires_in |
Token's expiration time in seconds. |
| 7 |
target_expires_at |
Token's expiration time stamp. |
| 8 |
target_error |
To map the error message received from the API end point. |
| 9 |
target_entitlements |
To map the entitlement object from the List Entitlement API end point. |
| 10 |
target_entitlement_starts_at |
To map the entitlement start date from the List Entitlement API end point. |
| 11 |
target_entitlement_ends_at |
To map the entitlement end date from the List Entitlement API end point. |
| 12 |
target_entitlement_product_id |
To map the entitlement product id from the List Entitlement API end point. |
Supported Placeholders
| S. No | Placeholder | Description |
| 1 |
{{email}}
|
User email from the app's login form. |
| 2 |
{{password}}
|
User password from the app's login form. |
| 3 |
{{client_id}}
|
Client ID added in the OAuth integration form. |
| 4 |
{{client_secret}}
|
Client Secret added in the OAuth integration form. |
| 5 |
{{member_id}}
|
Customer's unique ID from your provider, stored in our database. |
| 6 |
{{scopes}}
|
Scopes added in the OAuth integration form. |
| 7 |
{{starts_at}}
|
Start date of the subscription purchased from the app. |
| 8 |
{{ends_at}}
|
End date of the subscription purchased from the app. |
| 9 |
{{access_token}}
|
Access token stored in our database. |