Database Integration API Integrate your subscriber database directly with your MAZ app using a simple API endpoint.
MAZ offers a set of APIs which can be used by you to create your own Database Integrations.
Get Started
Navigate to Users, and select Database Integrations from the dropdown.
Select Custom Integration.
1. Enter an Integration Name
The custom name of the integration.
2. Select Subscription Type
The subscription type has two implications. First, it defines the unlocking mechanism in your apps. And second, it will determine the formatting of your API response. The subscription types are:
- All-Access: A simple boolean method that if true will unlock all content in your app that is locked by subscription.
- Duration-based: A date range method that will only unlock content with the cover date lying within the user’s active subscription date range. The content should have been locked by subscription.
3. Manage Login Types
This setting defines how your users will authenticate their subscription (ie. by entering email and password OR entering email and zip code, etc.). This is the user-generated data set that will be sent from MAZ to your API.
4. Provide Test Credentials
Provide test credentials to test various scenarios like Active/Expired/Invalid users in your app. You should provide at least one set of test credentials for each of the three cases viz. Active subscriber, Expired subscriber and Invalid subscriber. And this should be done for each login type.
5. Enable / Disable Single Sign-On (SSO)
Single Sign-On = OFF: One-way sync API endpoint
Single Sign-On = ON: Two-way sync API endpoint
6. Subscription Status URL
Enter the API URL where MAZ should send user login information and determine subscription access.
7. Notes
You may add some notes for either MAZ or for internal communication regarding your Custom Integration.
One-Way API Endpoint
The straightforward one-way database integration to validate and unlock app access for your existing subscribers hosted in your database.
Subscription Status
The Subscription Status API will check the current status of the user’s subscription. Subscription statuses can be requested when an existing user is signing-in and MAZ has no record of the user or when syncing access for print subscribers.
A successful response will return a status of "active": “true” for All-Access authentication and start and end dates of the subscription for Duration Based access.
Supported Authentication Parameters:
- email + password
- email + zip code
- account + zip code
- username + password
- mailing address
- account
Sample Request:
| curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d ' {"email": "user@email.com", "password": "123456"} ' https://www.YourDatabase.com/api/entitlements/status |
Sample Responses (response, code):
| All Access | Duration Based |
| {"active":"true", "member_id":"3"}, 200 | {"start_date":"mm/dd/yyyy", "end_date":"mm/dd/yyyy", "member_id":"3"}, 200 |
| {"active":"true", "member_id":"3", "title": "Custom Title", "description": "Custom Description"}, 200 | {"member_id":"3"}, 200 |
| {"error":"incorrect email/password"}, 400 | {"error":"incorrect email/password"}, 400 |
| {"error":"email not found"}, 404 | {"error":"email not found"}, 404 |
Single Sign-On (Two-Way Sync) API Endpoints
An SSO database integration solution to validate and unlock app access for your existing subscribers hosted in your database and data sync of in-app subscriber and single in-app purchases(feeds) records back to your database.
1. User Registration
The User Registration API will be used to pass user login info from MAZ apps and create a new record in your database. If a new user is created, you will return a “success” response and the UID (member_id) of the new user. The member_id should be the ID for this user within your database. Based on which registration/authentication cases are configured for your outputs, the parameters included in the response will vary.
Parameters:
- password
- platform
- facebook_token
- facebook_id
- twitter_token
- twitter_secret
- google_token
Cases:
- sign-up: email, password, platform
- facebook: email, facebook_token, facebook_id, platform
- twitter: twitter_token, twitter_secret, platform
- google: email, google_token, platform
We expect a member_id in response if the sign-up went through; member_id is the ID of the resource in the external database. This ID will be later used to make subscription purchase API calls whenever a digital subscription is purchased in the app.
2. Subscription Status
The Subscription Status API will check the current status of the user’s subscription. Subscription Statuses can be requested when an existing user is signing-in and MAZ has no record of the user or when syncing access for print subscribers.
A successful response will return a status of "active": “true” for All-Access authentication and a start and end date of the subscription for Duration Based access.
Parameters:
- email + password
Supported Authentication Parameters:
- account + zip code
- email + zip code
- address
- username + password
- email + password
Sample Request:
| curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d ' {"email": "user@email.com", "password": "123456"} ' https://www.YourDatabase.com/api/entitlements/status |
Sample Responses (response, code):
| All Access | Duration Based |
| {"active":"true", "member_id":"3"}, 200 | {"start_date":"mm/dd/yyyy", "end_date":"mm/dd/yyyy", "member_id":"3"}, 200 |
| {"active":"true", "member_id":"3", "title": "Custom Title", "description": "Custom Description"}, 200 | {"member_id":"3"}, 200 |
| {"error":"incorrect email/password"}, 400 | {"error":"incorrect email/password"}, 400 |
| {"error":"email not found"}, 404 | {"error":"email not found"}, 404 |
3. Subscription Update
The Subscription Update API will create a new subscription record in your database when a user purchases a subscription within a MAZ app. MAZ will periodically send subscription update calls to maintain consistent subscription records across all databases.
Parameters:
- member_id
- platform
- product_id
- startDate
- endDate
4. Reset Password
The Reset Password API will be used to trigger your internal reset password mechanism. A successful response will indicate that the email id has been found in your database and an email has been / will be sent to the user’s email id.
Parameters:
Request:
Responses (response, code):
Whitelisting MAZ Servers :
Please note that you will need to whitelist the following IP addresses of MAZ servers at your end for Database Integration to work:
Testing your Integration
Playground
To simplify the testing process, we have provided a testing environment on the Custom Integration page.
Using the “+Parameter” icon, add the parameters that you wish to test and fill in some testing data. When you click “Try Now” MAZ will ping your API URL, displaying both the request and the response. As noted above, you’ll need to match the response associated with your subscription type to successfully authenticate a subscriber.
Note: Parameters must be enabled under “Login Type” before being added for testing.
In-App Testing
You’ll want to test your integration in an app environment to be certain everything is working smoothly. The Custom Integration controls are connected directly to your app, so any changes made in the dashboard will go live immediately. That means you’ll be able to live test as soon as you update the dashboard.