Follow us
Tweet this!
(opens new window)
login
Username:


Password:



Forgotten username or password?
Register a new account

Authentication API

cloudware web authentication api logo

Cloudware Authorisation and Authentication API

NB we have prepared ready-made integration kits available to download and more are being planned.

Overview

The Cloudware City Website Authentication API is reliable and very straightforward to use.

Simply prepare the authentation api request message as follows...

You need to provide:

Send the request to https://auth.cloudwarecity.com/api/auth?<message>

A result message will be returned detailing the validity and what product(s) the user has access to, alongwith time to expiry (in case you want to enforce a timeout, or, as we recommend, warn the user that their subscription is about to expire).

The username and user id is also returned - it is strongly recommended that if you need to track users in your own systems that you use the user id for this purpose, as that will never change.

 

Examples

(these values are only examples, they will not function on demo or live platforms):

Per your Vendor Registration page you find the following details:

Site ID: 235
Prod ID: 34
API Key: 24bd5653aa08a6308716a08619acb6b976130a5f0c7f44919798c4afa71f2a7ed9068622

A user enters the following details into your login form:

username: username123
password: somesecurepass

Calculate the MD5 hash of the concatenation of email and password entered:

md5(user+password)

= md5("username123somesecurepass")

= 237df20a003e723d6f378762fc1a5635

Calculate the SHA-1 message security key hash by concatenation:

sha1(siteID + prodID + email + MD5 hash + API key)

= sha1("23534username123237df20a003e723d6f378762fc1a563524bd5653aa08a6308716a08619acb6b976130a5f0c7f44919798c4afa71f2a7ed9068622")

= 721345165722f58677554eaf1dc5941a79f04324

Use the above hashes and send the entire message to the authentication api URL:

https://auth.cloudwarecity.com/api/auth?sid=235&pid=34&us=username123&pw=237df20a003e723d6f378762fc1a5635&key=721345165722f58677554eaf1dc5941a79f04324

!

NB Ensure you use the calculated sha1 hash as the key, NEVER your secret API key.

 

The resulting XML response from the website authentication api details validity of the message, user/pass combination and if valid, the product ids and expiration (time remaining in seconds) of ALL the products the user is entitled to use at your site.

Valid response (user authenticated and allowed to use that product):

<cwcapi>
  <result>OK</result>
  <userid>59</userid>
  <username>username123</username>
  <email>firstlast@mydomain.com</email>
  <firstname>First</username>
  <lastname>Last</lastname>
  <products>
    <product id="34">
      <expiresecs>86366</expiresecs>
    </product>
    <product id="127">
      <expiresecs>2461968</expiresecs>
    </product>
  </products>
  <authcode>4418-3-487965891293417-26904</authcode>
</cwcapi>

This response tells you that the authentication including username and password was correct, and that the user has access to two products, ID 34 and 127, with expiry times 86366 (just under 1 day) and 2461968 (just over 28 days) respectively. User details are also returned (usernames can change but the userid will remain static - if you need to track a user in your site, use the userid value).

The AuthCode response is the authorisation number or 'transaction id' for this request - you should store this - if there is a need to contact Cloudware City Support due to an authentication problem, please quote this number.

Valid response (user authenticated but product subscription has expired)

<cwcapi>
  <userid>59</userid>
  <username>username123</username>
  <email>firstlast@mydomain.com</email>
  <firstname>First</username>
  <lastname>Last</lastname>
  <result>EXPIRED</result>
  <products>
    <product id="34">
      <expiresecs>-46</expiresecs>
    </product>
    <product id="127">
      <expiresecs>2968</expiresecs>
    </product>
  </products>
  <authcode>9198-3-208442601332047-78391</authcode>
</cwcapi>

This response tells you that the authentication including username and password was correct, and that the user has access to two products, ID 34 and 127, the first one having expired 46 seconds ago, the second one due to expire in 2968 seconds time.

Valid response (user authenticated but not authorised for that product)

<cwcapi>
  <result>NOTAUTH</result>
...

The rest of the response also includes the user's current valid products and expiry dates regardless.


Invalid response: (incorrect username/password)

<cwcapi>
  <result>INVALID</result>
  <authcode>8558-3-197265601317667-25082</authcode>
</cwcapi>


Malformed response: (key sha-1 hash does not verify - message integrity compromised)

<cwcapi>
  <result>MALFORMED</result>
  <authcode>1415-3-431421321627-72148</authcode>
</cwcapi>

 

 

API without product ID present

The use of product ID is optional in the API - in this case the API simply returns the list of products the user has susbcribed to and their expiry times.

This is used where a vendor has multiple products on their site and they want a single username/password login box, and their site determines which products that user has access to from the API response.

The result field will in this case not contain 'OK/EXPIRED' but instead 'VALID' to confirm the user has entered the correct credentials and distinguish between single and multi-product authentication.

e.g. using same details as above example:

Calculate the MD5 hash of the concatenation of email and password entered:

md5(user+password)

= md5("username123somesecurepass")

= 237df20a003e723d6f378762fc1a5635

Calculate the SHA-1 message security key hash by concatenation (without product id this time):

sha1(siteID + email + MD5 hash + API key)

= sha1("235username123237df20a003e723d6f378762fc1a563524bd5653aa08a6308716a08619acb6b976130a5f0c7f44919798c4afa71f2a7ed9068622")

= 721345165722f58677554eaf1dc5941a79f04324

Use the above hashes and send the entire message to the authentication api URL (no pid):

https://auth.cloudwarecity.com/api/auth?sid=235&us=username123&pw=237df20a003e723d6f378762fc1a5635&key=721345165722f58677554eaf1dc5941a79f04324

 

Invalid responses (INVALID, MALFORMED etc) are identical to the 'basic' authentication. There will be no 'OK' or 'EXPIRED' response since there is no product id to check against.

Valid response (user authenticated):

<cwcapi>
  <result>VALID</result>
  <userid>59</userid>
  <username>username123</username>
  <email>firstlast@mydomain.com</email>
  <firstname>First</username>
  <lastname>Last</lastname>
  <products>
    <product id="12">
      <expiresecs>-2384421</expiresecs>
    </product>
    <product id="17">
      <expiresecs>246968</expiresecs>
    </product>
  </products>
  <authcode>4418-3-487965891293417-26904</authcode>
</cwcapi>

As per above, this response tells you that the authentication including username and password was correct, and that the user has access to two products, ID 12 and 17, with expiry times -2384 (expired around 27 days ago) and 246968 (expires in just under 3 days) respectively.

The username and userid are returned (usernames may be changed but the userid will remain static - if you need to track a user in your site, use the userid numerical value - the above is user id '59').

The AuthCode response is the authorisation number or 'transaction id' for this request - you should store this - if there is a need to contact Cloudware City Support due to an authentication problem, please quote this number.

 

 

Test mode

Test mode allows the vendor to test the API from their application without having to purchase the product as a valid user (and whilst the product remains hidden/unavailable to purchase, to avoid any potential embarrassment!).

To use test mode, ensure the product ID is present and simply append &test=1 to the end of the API message URL.

Then use your user account/password that you log into Cloudware City as. It will return an OK response with 3600 seconds remaining on the product ID that was supplied in the API call.

 

We welcome any comments/suggestions for extending our APIs - please get in touch!