Table of Contents
- Overview
    - Sandbox Environment
- Authentication
- Creating Application User
- Acquiring Access Token

Overview

WorkSpan is an Ecosystem Cloud supporting various use cases. Companies and their business partners come to WorkSpan to collaborate and drive their business plans together. Data is always at the center of every successful partnership. So, through a set of Public External APIs, WorkSpan provides an easy way for the partners to bring their data into the system, subscribe to important events related to their workflows or feed the data they have inside to other internal/external systems. 

All of this can be achieved through a set of well documented RESTful APIs. Besides this, WorkSpan also provides connectors to some of the well known iPaaS (for e.g., PowerAutomate) platforms that developers can use to quickly develop tight integrations with their internal systems, no matter how complex their workflow can be.

Sandbox Environments

Multiple sandbox environments are used for development, testing, and demo work. Each sandbox environment has a separate URL for access from the browser. However, for accessing these sandbox environments, base URL for all environments will be https://api-sandbox.workspan.com.

Each sandbox environment is an independent environment, identified by ‘Environment Name’.

Example of sandbox environments:

Sandbox environment will be specified by adding ‘x-ws-env’ in the request header for each request with the value of the environment name.

E.g., HTTP Header

x-ws-env:  xxxx.workspan.com
Authorization: Bearer XXXXXXXX

Authentication

WorkSpan implements authentication with OAuth 2.0. External applications can use the Public Authentication API to authenticate with Application users and manage access tokens.

Creating Application User

“Application User” is created by the Company Administrator specifically to be used for access by an application using the WorkSpan External APIs. An Application User cannot login through Web UI. Application User is not added as a member of any object. However, application user has access to data of object where a company is a member of the object (Access level depends on the role of user of that company in that object). An application user is created with ‘Access type’.

Application user is assigned an id ; Application User Id (client_id) and  secret. Application Id is immutable. Secret can be reset any time, making the previous secret invalid.

Access Type: Access type is a predefined profile that provides access to a limited set of objects and operations (Read / Write / Link). For e.g., “ObjectRead”, “ObjectReadWrite”, “Object Dynamics_Read”, etc.

Steps to create “Application User”

Step 1: Company Admins in WorkSpan can register new Application users by going to their Company Profile. 

Step 2: On the company page, click on “Applications”, go to the “Application Users” tab and click on “Create Application User” as shown below:

Step 3: Fill in the Application User’s “Name” for e.g., “Report Export API” and under “Security Profile”, select “Object Read”, then click “Save”.

Step 4: Copy the secret key in a safe place as mentioned in the popup that will quickly be shown after the user is created.

Step 5: Then from the list of Application Users, open the newly created user and copy the user id.

Step 6: The pair of User ID and the Secret are needed for acquiring access token:

Application User ID: WS-ApplicationUser_ahFzfnZtd2FyZS1iaWctYmV0c3IZCxIPQXBwbGljYXRpb25Vc2VyGJHE9dwDDA

Secret:
cd3a1eaa3f5144a8a8494b2af1ef8b72e 

Acquiring Access Token

For OpenAPI documentation visit: https://developer.workspan.com

Method: POST
URL: https://api-sandbox.workspan.com/oauth/token
Headers:
x-ws-env - Specify environment if using any of the non-production environments, for e.g., uat.workspan.com
Content-Type: application/json

{
 "grant_type": "client_credentials",
 "client_id": "WS-ApplicationUser_ahFzfnZtd2FyZS1iaWctYmV0c3IZCxIPQXBwbGljYXRpb25Vc2VyGJHE9dwDDA",
 "client_secret": "cd3a1eaa3f5144a8a8494b2af1ef8b72e"
}

{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOm51bGwsInBhciI6eyJpc19jb21wYW55X2FkbWluIjpmYWxzZX0sIm9iaiI6ImFoRnpmblp0ZDJGeVpTMWlhV2N0WW1WMGMzSVdDeElKUVhWMGFGUnZhMlZ1R0lDQXdLTFZocDBKREEiLCJ1c3IiOiJXUy1BcHBsaWNhdGlvblVzZXJfYWhGemZuWnRkMkZ5WlMxaWFXY3RZbVYwYzNJWkN4SVBRWEJ3YkdsallYUnBiMjVWYzJWeUdOSFNqdG9EREEiLCJleHAiOjE2MzM3NjUxMjJ9.9oi5UQ203FUOnPjZW34Z-KTNsHOhHO641AYepYoQwNE",
 "token_type": "Bearer",
 "expires_in": 863999,
 "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOm51bGwsInBhciI6eyJpc19jb21wYW55X2FkbWluIjpmYWxzZX0sIm9iaiI6ImFoRnpmblp0ZDJGeVpTMWlhV2N0WW1WMGMzSVpDeElNVW1WbWNtVnphRlJ2YTJWdUdJQ0F3UHp1OVlvS0RBIiwidXNyIjoiV1MtQXBwbGljYXRpb25Vc2VyX2FoRnpmblp0ZDJGeVpTMWlhV2N0WW1WMGMzSVpDeElQUVhCd2JHbGpZWFJwYjI1VmMyVnlHTkhTanRvRERBIiwiZXhwIjoxNjMzNzY1MTIyfQ.C3oX1qcgI4JfWgQWjYHovuDsmncYOxiVvNQ2cif2LRw"
}

Note down the access token and pass it in the Authorization header when calling any of Public API endpoints. Example as given below:

Authorization: Bearer yJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOm51bGwsInBhciI6eyJpc19jb21wYW55X2FkbWluIjpmYWxzZX0sIm9iaiI6ImFoRnpmblp0ZDJGeVpTMWlhV2N0WW1WMGMzSVdDeElKUVhWMGFGUnZhMlZ1R0lDQXdLTFZocDBKREEiLCJ1c3IiOiJXUy1BcHBsaWNhdGlvblVzZXJfYWhGemZuWnRkMkZ5WlMxaWFXY3RZbVYwYzNJWkN4SVBRWEJ3YkdsallYUnBiMjVWYzJWeUdOSFNqdG9EREEiLCJleHAiOjE2MzM3NjUxMjJ9.9oi5UQ203FUOnPjZW34Z-KTNsHOhHO641AYepYoQwNE