Authentication

From Creately Developer

Jump to: navigation, search

Contents

Overview

To use a Creately API method, you will need to use a valid authentication approach. Authenticating to use the Creately API can be done using two different methods.

  • Client Token Authentication (CT)
  • Service Authentication (SA)

Important:

  • All API methods will support one or both of the authentication methods. The API method specification will denote which authentication method can be used.
  • Each authentication method used will require you to provide additional parameters when using a Creately API method. The additional mandatory parameters are defined in detail below in each section.
  • Each of the authentication methods allow you different levels of permissions and access. For details look at Permission.

Client Token Authentication (CT)

Client Token Authentication is when you use your Creately account credentials to authenticate with the API. This method is simple and allows you to easily access your Creately account and its data. This would be the most suitable method if your just need access to a single user account.

How this works

This is a state-full approach in which you will need to first use the API Login User method to obtain a Client Session Token (CST). This token will be a string that is the key to accessing any API method. The session token will be active as long as it is used. It will have a idle time out of 30 minutes. If the token is not used for 30 minutes to make any API call, it will expire. You will need to use the Login User method once again to obtain a new CST.

How to use

To use CT to access a API method

  1. Use the Login User method to obtain a valid Client Session Token (CST).
  2. Use the CST as a parameter in any API Method call

Parameters

When using CT to access the API, in each API method call the following parameters MUST be Included. Creately API will identify the authentication method and the user, based on these parameters.

Parameter Description
token The CST obtained during the Login User API method

Service Authentication (SA)

Service Authentication is when you use an API Key that is provided by Creately to authenticate the API. This method allows you to register users and managing them. If you wish to obtain a API Key please mail us on developer@creately.com. In your mail tell us.

  • Why do you need a API Key access for the Creately API?
  • How do you intend to use the Creately API?

IMPORTANT: The API Key and Shared Secret provided by Creately must be stored and handled securely. Creately will not be responsible for any misuse of the credentials.

How this works

This is a stateless approach which will required a valid API Key and a Shared Secret provided by Creately. In each API method request the API Key will need to be sent along with a Signature generated using the Shared Secret. The Signature must be unique to every API method request made. Creately API will use the Shared Secret assigned to the given API Key to validate the Signature and the overall request. Since the Signature is generated for each request there will be no expiration time for the Key or signature.

How to use

Once you have obtained a valid API Key and Shared Secret from Creately, you will need to follow the steps below to generate a signature for each request.

1. Build a string with the URL of the method end point and all its parameters in the form of a HTTP GET request. Include the API Key as well.

String baseURL = "http://creately.com/api/document";
String requestParamsNotSorted = "apikey=apikeystring&param1=value1&param2=value2&param3=value3";

2. URL Encode & Canonicalize the URL.

.NET :

baseURLEncoded = HttpUtility.UrlEncode(baseURL, System.Text.Encoding.UTF8).Replace("+", "%20").Replace("*", "%2A")
                                                                              .Replace("%7E", "~").Replace("\@", "%40")

JAVA :

baseURLEncoded = URLEncoder.encode(baseURL, "UTF-8").replace("+", "%20").replace("*", "%2A").replace("%7E", "~");

3. Sort the params of query strings in step 1 and Canonicalize key and value. ex. Sort

String requestParamsNotSorted = "apikey=apikeystring&usr=test-api@test.com&action=exists";

to

String requestParamsSorted = "action=exists&apikey=apikeystring&usr=test-api@test.com";

and Encode to

String requestParamsSorted = "action=exists&apikey=apikeystring&usr=test-api%40test.com";

NOTE: Encode key and value separately and combine them to make the request parameters string

4. Uppercase the URL encoded chars(.NET only) in step 2 & 3.

5. Create string to be signed using URL encoded base URL and request parameters list

String toSign = baseURLEncoded + "?" + requestParamsSorted;

6. Add the shared secret to the end of the string to be signed i.e. String of step 5 + secretKey.

String toSign = baseURLEncoded + "?" + requestParamsSorted + secretKey;

7. Get an hmac_sha1 key from the raw key bytes of secret string - this step isn't required for PHP users.

VB.NET :
System.Text.Encoding.UTF8.GetBytes(secretKey)
JAVA :
SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes(), "HmacSHA1");

8. Hash the string in step 6 with the key created in step 7.

9. Convert the string in step 8 to base64 String.

10. URL Encode the string generated in step 9.

11. Uppercase the lower case characters in URL Encoded string in step 10 (.NET only).

12. Attach the Signature generated in step 10 as a parameter to your POST request.

Now your request is ready to go.

Source code examples for generating the signature are available in VB.NET, JAVA and PHP - Right click and choose Save as to download the files.

Parameters

When using SA to access the API, in each API method request, the following parameters MUST be Included. Creately API will identify the authentication method and the user using these parameters.

Parameter Description
apikey The API Key provided by Creately
sig The Signature generated for the request using the Shared Secret
uid The Creately User ID of the user on who the request will be performed. You can avoid this parameter if the "usr" parameter is provided
usr The registered email address of the user on who the request will be performed. You can avoid this parameter if the "uid" parameter is provided


Browser Authentication

Above methods would let you authenticate to use the Creately API. But you will not be able to allow the authenticated user to use creately.com or the Creately Application by redirecting them to the respective URL's. This is because the users browser needs to be authenticated to the creately.com site before the user can access his/her account in creately.com.

For this you can use the following approach to tell creately.com to authenticate the user. Follow these steps.

  1. Have a valid set of credentials to authenticate the Creately API (Either through CT or SA). If you are using CT, you will need to obtain a CST through a Login User method call.
  2. Use Browser Login method call to obtain a Temporary Redirect Token (TRT). See detailed explanation below for TRT.
  3. Redirect the user in the browser to Browser Login URL. If you want the user to be taken to a specific location, you can do that in the Browser Login URL using a parameter.

Temporary Redirect Token (TRT)

This is a token that is created for validating a user login from Creately API to Creately Site. When a TRT is created through the Browser Login method, it will contain details about the user who is supposed to be logged into the browser. The Creately Site will use the details to log the user into Creately.com. The token will function based on the following rules.

  • A TRT can only be created using the Browser Login API method.
  • The token can only be used with the Browser Login URL.
  • The token can only be used once. After the first usage the token will expire.
  • The TRT has a life span of 60 seconds. If the token is not used within 60 seconds it will expire.
Personal tools