OAuth Authentication

Request an access token via OAuth 2.0 if you are developing an app for multiple users. This will allow WorkBoard to dynamically authenticate any of your app users to give them access.

1. Register your app

To start using WorkBoard's API, you first need to register your application on WorkBoard (click on the "App" tab). You will be asked to provide the following information:

  • App Name - A name for your application.
  • App Description - A short description of your application.
  • App Redirect URI - You must provide a redirect URI for authentication. It will be matched with the URI that you pass in the OAuth request. (Be sure to save this URI for use in your future requests)
  • Contact Person Email Address - If an error occurs, the WorkBoard API will send a notification to this address.

Once you have created an app, you will receive a Client ID (which will identify your app to the WorkBoard API), and a Client Hash. Both of these will be used in the OAuth authentication process.

Important: Remember to treat your Client Hash like a password. It can be used to access your organization's WorkBoard data, so be sure to store it somewhere safe!

2. Request an authorization code

To start the authorization process, submit a request to the authorization URL. Include the parameters listed below.

Authorization URL: https://www.myworkboard.com/wb/oauth/authorize

Parameters
client_id The Client ID you received when you registered your app (Required)
redirect_uri The URL in your app to which WorkBoard will redirect after authorization
scope A comma-separated list of scopes. In WorkBoard API v1.0, the default value is "all." (Optional)
state A random string, used to protect against cross-site request forgery attacks. WorkBoard will redirect to the specified redirect_uri with the same value passed in the state parameter. If the two values don't match, the access call should be aborted. (Optional)
response_type If you prefer to receive the authorization code over JSON response (not recommended), set the value of response_type to "json_code." (Optional)

Once you have successfully submitted your authorization request, you will be redirected to the redirect_uri that you provided, with the code parameter set to the authorization code.

If an authorization error occurs, you will be redirected to the redirect_uri with following parameters set to summarize the error:

Error codes
invalid_client_id Occurs if the client_id parameter provided with the request was invalid
invalid_scope Occurs if the scope parameter provided with the request was invalid 
# Sample Request
https://www.myworkboard.com/wb/oauth/authorize?client_id={client_id}&state={random_string}

# Sample Success Response
{
    "success" : true,
    "code" : "Authorization code",
    "state" : "random_string"
}

# Sample Error Response
{
    "success" : false,
    error: "error_code"
    error_message: "Description error message"
    state: "state value as passed in request"
}

3. Exchange your authorization code for access credentials

To request access credentials, execute a POST request to the Token URL below with your authorization code.

Note: the authorization code is valid for 5 minutes. If you do not request your access token before the authorization code expires, you will need to repeat step 1.

Token URL: https://www.myworkboard.com/wb/oauth/token

Parameters
client_id The client id you received when you registered your app (Required)
client_hash The client hash you received when you registered your app (Required)
code The authorization code you received in Step 1. (Required)
redirect_uri The URL in your app to which WorkBoard will redirect after authorization (this URL must match the redirect URI that was used in registering your application)
state A random string, used to protect against cross-site request forgery attacks. WorkBoard will redirect to the specified redirect_uri with the same value passed in the state parameter. If the two values don't match, the access call should be aborted. (Optional)

The access_token is valid for one year, and can be revoked with https://www.myworkboard.com/wb/oauth/revoke/

# Sample Request
POST https://www.myworkboard.com/wb/oauth/token
Payload:
client_id={client_id}
client_hash={client_secret}
redirect_uri={redirect_uri}
code={authorization_code}

# Sample Response
{
    "success" : true,
    "access_token" : "[Your access token]",
    "scope" : "[Granted scope (if requested)]",
    "token_type" : "bearer"
}

4. Using access_token in your API requests

Every request to the API should be made via HTTPS and must include your access_token, which must be passed in the authorization header.




# Sample Request
curl -X GET -H "Authorization: bearer {access_token}" https://www.myworkboard.com/wb/goal/123