Programatic License Issuing
If you want to simplify the process of issuing licenses to your customers you will probably want to use our license issuing API.
It is a simple API which you can call programatically. You should do this from a script which is triggered by a callback from your payment provider. Your script will interact with our simple REST API to generate a license key for the user who has just purchased a license. It can then email the license directly to the user with no intervention from you or us. The user can input this license key directly into their application and their application will be registered.
The API uses an authentication system based on OAuth. Each application has an associated secret key. You use this secret key to generate a hash signature which you send along with your request. When we recieve the request we check the signature and we will only issue licenses where it is valid. Because the secret key is kept secret and never transmitted it is impossible for someone to fraudulently issue licenses for your application.
Below we provide a step by step description of the process for interacting with our API and signing your request. We also provide a full PHP script which shows the process in action. If your web server supports PHP then you can simply edit our script to your needs, otherwise it should be simple to translate to any other serverside language.
Find your application ID and secret
Simply log into your Sharify administration panel and click on "List and edit your applications". Click the "Edit" button next to the correct application and note down the "Unique ID" and "Secret".
Prepare your parameters
You need to pass certain parameters to our license issuing API. These are:
- The email address of the user who has just registered.
- The name of the user who has just registered.
- The reference for this payment from your payment provider. This will help you to cross reference your records later.
Generate your signature
You now need to generate your signature. You concatenate each parameter name and value in alphabetical order onto the end of your applications secret. The string will look something like the following with each of the highlighted words swapped for their real value:
You now take an md5 hash of this string and that is your signature.
Call our API
The endpoint for our API is http://www.sharify.it/api/2/license/issue/
(The current version of the API is 2, hence the 2 in the URL)
You append your application's unique ID to this URL and then append a querystring with all of the above parameters, including the generated signature. The parameter name for the signature is api_aig.
So the complete URL will look something like the following (with the highlighted words swapped for their actual values):
Parse the returned XML
Our API will return an XML document which describes the status of your request. If the request was successfull then the document will look something like this:
<response api_version="2" status="106"> <data><![CDATA[GENERATED_KEY]]></data> </response>
The success status is 106 and the generated key is included in the data element.
If your api signature was invalid you will instead get some XML like this:
<response api_version="2" status="904"> <data><![CDATA[Invalid api_sig]]></data> </response>
If you make another mistake with your request (e.g. wrong application ID) then you may recieve a HTTP 404 error code instead.
Email the user their license key
Assuming you made a valid request to our API then your script will now know the generated license key for this user. You should email this key to the user so they can enter it into their application to unlock it.
As you can see, the API is very simple to interact with. The only hard part is generating the signature and that is pretty easy if you follow the instructions above. If you would prefer to read code than descriptions then please check out our example PHP script which does all of the above.
As always, if you have any questions or comments then please contact us.