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:
- 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:
|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|
- 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.
- You'll get back an object with the following fields, all of which are relevant:
|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.|
- 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
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.