VL Group

Rhymba v3.6 Documentation


The Rhymba Search API uses just your system/application access token for requests. But for requests to APIs that have a potential financial impact for you — e.g. Purchases, Downloads, and Streaming — you want to secure your requests a little better.

Enter: Access secrets and two-step authentication.

Rhymba Purchase, Streaming, and Download API Authentication, In a Nutshell

Securing your API requests to those services works like so:

  1. Make a request from your serverside environment to the appropriate token endpoint. For Purchases, this is https://purchases.mcnemanager.com/token.create. For Downloads and Streaming, you hit the Content API, so it's https://dispatch.mcnemanager.com/current/token.create. As a part of your request, you should pass the following fields in the HTTP headers. We strongly recommend HTTPS, even though this call will likely be a server-to-server one. Required headers are in bold:
Field Name Type Description Example
access_secret string Access secret for your system provided by VL Group.
access_token string Access token for your system provided by VL Group.
method string Name of the API method the hashed access tokens will be used for eventually. GetInvalidItems
ttl integer The TTL (time to live) for the hashed access token that will be generated, in seconds. 180
use_limit integer Hard limit on the number of reuses of the hashed access token that will be generated. This is optional. 3
  1. In addition to these required parameters you must pass all the the parameters that will be passed when you call the content server for your content. If this is a GetStream call you must pass the required parameters of GetStream. If it's a Download Session Token, you must do the same. See Streaming and Downloads for more info.
  1. You'll get back an object with the following fields, all of which are relevant:
Field Name Type Description
access_hint string Access hint for your system provided by VL Group.
access_req string The temporary hashed access request token to be used for authorized requests to the API method it was created for in Step 1.
access_token string Temporary access token for the specific request you're going to be making. This will differ from your regular system/application Rhymba access token.
  1. All three of the elements returned as part of Step 3 above should be included in any GET (as the access_token, access_hint, and access_req query string parameters) or POST (as HTTP headers named access_token, access_req, and access_hint) calls to the Rhymba Purchase or Content API. They will only be valid for use when calling the method specified in Step 1, and only for the the amount of seconds from creation specified as the TTL in Step 1 (or, with a hard cap of N uses, where N is the use_limit specified in Step 1).

Keep It Secret, Keep It Safe

DO NOT GENERATE THESE HASHES IN CLIENT-SIDE SCRIPT, OR APPLICATIONS RUNNING ON END USER MACHINES, ESPECIALLY THOSE WRITTEN IN WRITTEN ON JIT-LIKE PLATFORMS! This includes Javascript, Flash, Silverlight, and even Java, .NET, and more. Doing so will necessarily expose or potentially expose your system/application's access secret to end users. In addition, anything running on an end user's machine is likely to be able to be decompiled or analysed to determine your access secret. Obfuscation is not security.

A better design is implementing your own user-by-user access rule to your own servers, and then having your servers talk to ours for these sorts of chargeable events. It's likely that any client-side app you create already will have some form of user authentication and unique access in it, so we recommend you piggy-back off of that and leave your Rhymba access credentials secure.

You will be responsible for any usage, bandwidth, and other charges accrued as a result of your access secret being compromised as a part of your application's design & deployment.

We can, of course, help advise you when designing your applications to be as secure as possible when talking to Rhymba. If you have any questions or doubts or concerns, please contact us for assistance and guidance.