API: OAuth2 and GraphQL Integrations

If you're looking for push notifications / webhooks integration, please navigate to Webhooks Section instead.
If you're looking for the API requests schema, open up the API Explorer.

Getting Started

The general flow for any API call / user authorization as follows:

1. Create an OAuth2 application under Profile Settings
2. Assemble an OAuth2 authorization link
3. Receive a redirect to one of your application URLs from an end-user (content provider, subscriber or just any user). Exchange the code taken from the query string for an access token by making a POST request to the OAuth2 API of our website.
4. Use the access token to make API calls
5. Refresh your access tokens each month

Integration

Navigate to Profile Settings and find "Add Integration" button.
In the popping up form you'll need to specify a redirect URL and pick the right scopes for your app.

Authorization scopes

With the authorization scopes you specify permission level to an end-user (you, your subscriber or any user) account. The end-user will see what scopes you requested to be authorized. If you ask for a permission to more than you actually need, it's highly likely to be rejected by a user.

The OAuth2 scopes are not inclusive. In other words, if user.subscriptions.read scope is authorized, the access is provided to the subscriptions data, while access to other user fields can be opened only with user.read authorized scope.

The OAuth2 scopes are combinable. In other words, if subscriber.read is authorized, it may not allow you to have an access to email field of the subsciber, while two scopes subscriber.read and user.email.read authorized at the same time will provide you with an access to subscriber data including their email. More details on that can be found in the GraphQL documentation below.

In order to ask user for a permission under desired scopes, you need to direct them to an Authorization URL. Just build and share a link of the following format:

https://www.subscribestar.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL&response_type=code&scope=ONE_OR_MULTIPLE_SCOPES

Let's go through each request parameter:

• client_id — The Client ID taken from OAuth Apps section under Profile Settings for this app
• redirect_uri — The Redirect URL you specified in the OAuth Apps section under Profile Settings for this app
• response_type — Keep it always code
• scope — The scope(s) you want the end-user to authorize for you. If multiple separate by + in the URL.
  For example: &scope=user.read+user.email.read.

Upon accessing the URL you've built the end-user will see a page with the list of scopes and two buttons: "Allow" and "Deny". Each button redirects them to the same Redirect URL with different parameters.

Redirect URLs

Redirect URL is typically your website URL which will be receiving redirects from user authorization flow on our website. If user granted you access by hitting "Allow" button from the previous step, a code parameter will be added to the query string. For example, if a redirect URL was https://foo.io/auth, then you'll be receiving GET requests to your website like this:

https://foo.io/auth?code=LKOUqgt37yFqJwotlK9urVzI_vC_mg5liWnb9u8DIQY

This code you exchange for an authorization token.

If user didn't allow you to have an access per listed scopes, then you'll be receiving a redirect with error parameter:

https://foo.io/auth?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.

Authorization tokens

An authorization token is used to make actual API calls (typically receiving information about a user who granted you an access to their data).

To exchange the code received in the previous step, make the following POST request to https://www.subscribestar.com/oauth2/token endpoint:

POST https://www.subscribestar.com/oauth2/token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=YOUR_REDIRECT_URL

Let's go through each request parameter:

• client_id — The Client ID taken from OAuth Apps section under Profile Settings for this app
• client_secret — The Client Secret taken from OAuth Apps section under Profile Settings for this app
• code — The code you received on the previous step
• grant_type — Keep it always authorization_code
• redirect_uri — The Redirect URL you specified in the OAuth Apps section under Profile Settings for this app

The response will be:

{
  "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}

Store this data in your database. refresh_token will be used to obtain new access_token after it expires in expired_in seconds. For majority of integrations it's set to 1 month, though we always recommend relying on actual data received from the API.

Now it's time to make real API calls with the help of obtained access_token.

Making API calls

Each API call is authorized with Authorization: Bearer <access_token> HTTP header and sent via POST request. Where access_token is the token you obtained from the previous steps, for example:

curl --request POST \
  --url https://www.subscribestar.com/api/graphql/v1 \
  --header 'Authorization: Bearer de6780bc506304a6309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54' \
  --data '{"query":"{ subscriber { name } }"}' \
  -H "Content-Type: application/json"

We use GraphQL API, which is really easy and flexible, you can get familiar with it on Official GraphQL Page.
The clean structure of the subscribestar.com GraphQL nodes without Relay Elements (images are clickable):



The full structure reflecting connections and pagination edges:

The request parameters are:

• query — GraphQL query, for example: { user { name } }
• variables — GraphQL variables used in the query, the parameter is optional

API explorer

The API Explorer is both a reference guide and interactive tool.

In the Documentation for the API Exolorer you will discover lists of all available actions, made up of endpoints, methods, and parameters – key building blocks in your API requests. It also effectively lists the main resources available to you through our API.

Also, you can run queries on real data using the Explorer, an integrated development environment in your browser that includes docs, syntax highlighting, and validation errors. You can use checkboxes and fields of the GraphQL API Explorer to build GraphQL queries.

API Explorer can be used to request the exact data you need, and therefore limit the number of requests you need.

Open API Explorer in a new browser window at 100% screen width. Just click "Show Documentation Explorer" icon in the upper left corner of the opened API Explorer to start exploring API documentation. You can search schemas to view descriptions and supported fields.

Pagination

Some resources are paginable. For example, payments and subscriptions (represented as a Connection node). Learn more about pagination in the official GraphQL docs. Try out the following query to learn about cursor navigation:

{
  user {
    payments {
      edges {
        node {
          id
          amount
        }
        cursor
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
    }
  }
}

It will return:

{
  "data": {
    "user": {
      "payments": {
        "edges": [
          {
            "node": {
              "id": "412612",
              "amount": 499
            },
            "cursor": "MQ"
          },
          {
            "node": {
              "id": "401850",
              "amount": 100
            },
            "cursor": "Mg"
          }
        ],
        "pageInfo": {
          "hasNextPage": true,
          "hasPreviousPage": false,
          "startCursor": "MQ",
          "endCursor": "Mg"
        }
      }
    }
  }
}

Take the cursor from the response and paginate backwards or forward:

{
  user {
    payments(after: "Mg") {
      edges {
        node {
          id
          amount
        }
        cursor
      }
      ...

Using Refresh Tokens

When your access token expires, you must refresh it by using the refresh_token you received in the response upon initial access token request (described in the beginning of this document). A sample request in order to receive fresh access token:

POST https://www.subscribestar.com/oauth2/token?client_id=YOUR_CLIENT_ID&client_secret=SECRET&refresh_token=KNOWN_REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=YOUR_REDIRECT_URL

Same with curl:

curl -F grant_type=refresh_token \
   -F client_id=9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f \
   -F client_secret=d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2 \
   -F refresh_token=c65b265611713028344a2c285dfdc4e28f9ce2dbc36b9f7e12f626a3d106a304 \
   -X POST https://www.subscribestar.com/oauth2/token

The response would be:

{
  "access_token":"ad0b5847cb7d254f1e2ff1910275fe9dcb95345c9d54502d156fe35a37b93e80",
  "token_type":"bearer",
  "expires_in":30,
  "refresh_token":"cc38f78a5b8abe8ee81cdf25b1ca74c3fa10c3da2309de5ac37fde00cbcf2815",
  "scope":"user.read"
}

Learn more about OAuth2 in details on Official OAuth2 website.

Integration Examples

• PHP
• CURL
• Having your code snippets? Do share with our Support Team!