Follow

Authorization

Connectworks API uses the OAuth 2 standard (http://tools.ietf.org/html/rfc6749) for authorization.

A registered application will need to perform the following steps to be authorized to use the API.

 

Your application captures the users credentials

This approach requires your application to be assigned the password grant.  It is intended to be employed in situations where your application captures the users username and password directly rather than by way of a redirect.

In this case you may obtain a token direct from POST https://app.connectworks.com/oauth/token by passing the following parameters:

Parameter Value Required Comment
client_id {YOUR_CLIENT_ID}  Yes Client ID of your application.
client_secret {YOUR_CLIENT_SECRET} Yes Client secret of your application.
grant_type password Yes The password grant.
username {USERS_USERNAME} Yes The username obtained from the user (i.e. their login email address).
password {USERS_PASSWORD} Yes The password obtained from the user (i.e. their login password).

In response you should receive some JSON containing either an error message or the appropriate access token:

{
  "access_token":"58d89ae2-YYYY-YYYY-YYYY-YYYYYYYYYYYY",
  "token_type":"bearer",
  "refresh_token":"9db8a7a1-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "expires_in":5182643,
  "scope":"read upload write"
}

You may easily test the above mechanism use curl as follows:

curl -H "Accept: application/json" https://app.connectworks.com/oauth/token -d grant_type=password -d username={USERS_USERNAME} -d password={USERS_PASSWORD} -d client_id={YOUR_CLIENT_ID} -d client_secret={YOUR_CLIENT_SECRET}

Your application is a web application

You should use this when your users access your application using an internet browser.  In this case you pass control to us to capture the users login credentials and authorisation.

Step 1: Get the Authorization Code

GET https://app.connectworks.com/oauth/authorize

Parameter Value Required Comment
client_id {YOUR_CLIENT_ID}  Yes Client ID of the application
response_type code Yes  
redirect_uri {YOUR_REDIRECT_URI} Yes Redirect URL of your application

You will be redirected to {YOUR_REDIRECT_URL} with one request parameter - "code".

Step 2: Get the Access Token

POST https://app.connectworks.com/oauth/token

Parameter Value Required Comment
code {CODE_FROM_STEP_1}  Yes The code parameter received from step 1.
grant_type authorization_code Yes This requests a token from the code above.
redirect_uri {YOUR_REDIRECT_URI} Yes Redirect URL to your application.

You will need to pass your client ID and secret as Basic authentication parameters in the post.

You will be redirected to {YOUR_REDIRECT_URL} with the following parameters: access_token, refresh_token, expires_in, token_type, scope.

If the access token has expired, use the refresh token to get the new access token.

POST https://app.connectworks.com/oauth/token

Parameter Value Required Comment
refresh_token {REFRESH_TOKEN}  Yes The refresh token from Step 2
client_id {YOUR_CLIENT_ID} Yes Client ID of the application
client_secret {YOUR_CLIENT_SECRET} Yes Client Secret of the application
grant_type refresh_token Yes  
redirect_uri {YOUR_REDIRECT_URI} No Redirect URL of your application

Using the token

To use the token you simply include the following in all API request headers:

Authorization: Bearer _____


Where _____ is the access token retrieved above.

In addition your application should always includes sensible retry logic to handle cases where a request is not able to be served on an intermittent basis.  This will avoid having to deal with the odd 504 gateway errors that occur on occasion. 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk