AudiencePlayer API access

AudiencePlayer API access

1. General information

The AudiencePlayer API is based on the GraphQL specification. For more information, please see GraphQL.

  • You can find the GraphQL documentation here (including latest version tag and date of deployment information):
    ☞ https://api.audienceplayer.com/documentation

  • In addition to that, a graphic user interface (GUI) is available via the browser, so that you can expressively construct queries and mutations, execute them and browse through the auto-generated documentation (see section 2).
    Contact support for more information regarding your specific endpoint specification.

2. Graphical API interface

We offer an expressive graphical user interface "GraphiQL" on top of our API.

DEMO example:


GraphiQL is an very useful tool to debug your queries/mutations and directly test API-interaction. We recommend using this interface in the Google Chrome browser.
Many queries and mutations require an authenticated User. You can conveniently place your OAuth token, which you obtain via ClientAuthenticate or UserAuthenticate, in the headers" panel.

3. Headless integration

In case you would like to integrate our services directly into your own frontends (e.g. website, mobile app etc), you can integrate with the afore mentioned programmatic endpoint. Below we have highlighted the most essential authentication mutations you need.

Additionally, you will need to integrate our player in your own frontends. See our player library for WEB: Video player embedding 


3.1 ADMIN SCOPE (CMS)

You can authenticate an existing CMS-administrator directly via an Oauth2 password grant ("traditional user login"), which is useful for quick tests and/or custom updates e.g. via the graphical interface.

  1. mutation {
  2.     UserAuthenticate (
  3.         project_id: 123
  4.         email: "email@example.com"
  5.         password: "****"
  6.     ) { access_token }
  7. }

For a more elaborate automated flow, you should authenticate via an "Oauth2 client grant" and implement a "server-to-server" programmatic access flow. You can obtain the relevant client-credentials via CMS > Project configuration > Integrations > AudiencePlayer API > "ADMIN scope".
☞ N.B. only use these credentials for server-2-server communication, credentials must never be publicly exposed!

  1. mutation {
  2.     ClientAuthenticate (
  3.         project_id: 123
  4.         client_id: "a23f"
  5.         client_secret: "****"
  6.     ) { access_token user_id user_email }
  7. }

 

3.2 USER SCOPE (frontend users)

You can authenticate an existing frontend user directly via an Oauth2 password grant ("traditional user login").

  1. mutation {
  2.     UserAuthenticate (
  3.         email: "email@example.com"
  4.         password: "****"
  5.     ) { access_token }
  6. }

For a more elaborate automated flow, you should authenticate via an "Oauth2 client grant" and implement a "server-to-server" programmatic access flow. You can obtain the relevant client-credentials via CMS > Project configuration > Integrations > AudiencePlayer API > "USER scope".
☞ N.B. only use these credentials for server-2-server communication, credentials must never be publicly exposed!
  1. mutation {
  2.     ClientUserAuthenticate (
  3.         project_id: 123
  4.         client_id: "a23f"
  5.         client_secret: "****"
  6.         user_id: 123              # or alternatively: user_email: "email@example.com"
  7.         auto_register: true   # set "auto_register" to true for auto-creation if User doesn't exist
  8.     ) { access_token, user_id, user_email }
  9. }

3.3 Single Sign-On

If you have configured third-party OAuth2 authentication providers in the CMS, you can also leverage the existing AudiencePlayer API queries to integrate Single Sign-On in your own custom front-end environment.
For more information, please see: Single-Sign-On.

3.4 WEB-template authentication hook

If you generate User access_tokens in your own environment, and would like to login Users automatically on the AudiencePlayer WEB-template, you can redirect to its url and add the access_token as a query parameter to any WEB-template URL. The corresponding User is automatically logged in, overriding any pre-existing session:
  1. https://demo.audienceplayer.com/?token=eY...

3.5 Authorisation hook

If you need to control which Users are entitled to which Subscriptions or Products, you do so through our API (for instance if you manage payments yourself, or Users should obtain access to AudiencePlayer Subscriptions/Products because they have purchased some external product on an external website). Depending on your use case, you could fully integrate with all the fine-grained mutations and queries that are available to create (zero-sum) payment orders and entitle Subscriptions or Products (see the extensive GraphQL documentation for admin scope).

If you are simply looking for a convenient way to immediately entitle a single User with a certain Subscription or Product, you can use the examples below. Note that these examples can be used for already existing Users (by passing "user_id"), or can be used to auto-create a User at the same time (by passing "user_email" and "auto_register").
Obviously you can also first run the "ClientUserAuthenticate" mutation (see section 3.2 above), to obtain the "user_id" and a valid token.

Product entitlement example
☞ N.B. only use these credentials for server-2-server communication, credentials must never be publicly exposed!
  1. mutation {
  2. ClientUserProductEntitlementManage (
  3. project_id: 111, # the ID of your your AudiencePlayer account
  4. client_id: "222", # OAuth2 client ID (obtained in CMS from the User-scope OAuth2 credentials)
  5. client_secret: "abc", # OAuth2 client SECRET (obtained in CMS from the User-scope OAuth2 credentials)
  6. user_id: 333, # ID of the AudiencePlayer User, or alternatively: user_email: "email@example.com"
  7. auto_register: true        # set "auto_register" to true for auto-creation if User doesn't exist (only together with "user_email")
  8. product_id: 444, # ID of the AudiencePlayer Product that the User should receive
  9. action: fulfil # "fulfil" or "revoke" the entitlement (if the 3rd-party order is refunded, the entitlement should be revoked)
  10. )
  11. }

  13. # Webhook format
  14. https://api.audienceplayer.com/graphql/111/user/?query=mutation{ClientUserProductEntitlementManage(project_id: 111,...)}

Subscription entitlement example
☞ N.B. only use these credentials for server-2-server communication, credentials must never be publicly exposed!
  1. mutation {
  2. ClientUserSubscriptionEntitlementManage (
  3. project_id: 111, # the ID of your your AudiencePlayer account
  4. client_id: "222", # OAuth2 client ID (obtained in CMS from the User-scope OAuth2 credentials)
  5. client_secret: "abc", # OAuth2 client SECRET (obtained in CMS from the User-scope OAuth2 credentials)
  6. user_id: 333, # ID of the AudiencePlayer User, or alternatively: user_email: "email@example.com"
  7. auto_register: true                 # set "auto_register" to true for auto-creation if User doesn't exist (only together with "user_email")
  8. subscription_id: 444, # ID of the AudiencePlayer Subscription that the User should receive
  9. expires_at: "2000-12-31T12:30:00Z", # Expiry date (UTC) of the User Subscription
  10. action: fulfil # "fulfil" or "revoke" the entitlement (if the 3rd-party order is refunded, the entitlement should be revoked)
  11. )
  12. }

  14. # Webhook format
  15. https://api.audienceplayer.com/graphql/111/user/?query=mutation{ClientUserSubscriptionEntitlementManage(project_id:111,...)}

4. Rate limits

By default, rate limiting is applied to all API-requests. This means, we limit the amount of requests you are allowed to make:

  • Per minute (default 120 requests per minute). The following sensitive queries have a lower limit:
    • "Password request/modify" mutations: 6
    • "Authentication" mutations: 20
    • "Telemetry" queries: 30
  • Per unique User (based on a finger print which is derived from User-IP, User-Agent etc).

All platform tools provided and managed by AudiencePlayer (such as the WEB-template, TV-apps, etc) take this into account.

☞ Take rate limiting into account particularly if you develop your own server-2-server integration with the AudiencePlayer API. For instance if you have one service which queries our API on behalf of many Users. Ensure your requests are uniquely fingerprinted by our API e.g. by, implementing the `X-Forwarded-For` header so that you may forward the end-User IP address.

 


    • Related Articles

    • Zapier

      Connecting AudiencePlayer to a CRM or Accounting app of choice with Zapier This guide will walk you through the process of connecting your CRM or Accounting app to AudiencePlayer using Zapier. The AudiencePlayer integration ensures that user data and ...

    • File upload specifications

      ☞ For more information on how to upload via the CMS, please see: CMS > Content > Assets. ☞ For more information on bulk/3rd-party uploading, please see: Bulk video upload. ☞ For more information on general best practices, please also read our blog ...