Intralinks Developer Portal

The root container for all objects on the Intralinks platform is the workspace. Workspaces are where you create folders, upload documents, and add users or groups. Workspaces support a number of different security features that affect how you interact with them, with the most common being a splash screen. Splash screens allow the owner of the workspace to supply additional information about the workspace like legal or other usage restrictions that require you to click an “Agree” or “Continue” button before being allowed to open the workspace.

Example Splash Screen

Other options enable multi-factor authentication or other custom rules the owner can specify. Workspaces that have these features turned on will require additional steps with each new user session in the form of a series of calls to the workspaces/entry API before other actions like listing documents will work. If you don’t properly “enter” the workspace before making additional API calls, you will receive a 303 HTTP Status error with the following error text:

For V1 APIs:

<error>
     <code>303</code>
     <message>Workspace entrance requirements not met.</message>
     <subCode>1</subCode>
</error>

For V2:

{
  "errors": [
    {
      "code": 303,
      "subCode": "1",
      "message": "Workspace entrance requirements not met."
    }
  ]
}
Multi-Factor Security settings

The first set of requirements you will have to deal with are any multi-factor authentication settings that are enabled on the workspace. You can tell what kind of security is enabled on the workspace by looking for the securityLevel property in the workspace meta data. These settings are all controlled by the workspace administrators. Below are the core security levels supported on the core platform.

1 = Standard security which requires no additional actions

2 = Risk-assessed challenge question, then one-time password

3 = Risk-assessed challenge question

4 = Risk-assessed one-time password

5 = Always challenge question

6 = Always one-time password

7 = No weekend access

8 = Restricted IP

9 = Time match

Risk-assessed variations add the additional layer of adaptive authentication to determine whether you are presented with a one-time password request or challenge question.

Entry Procedures

If the workspace has a challenge question or other type of security requirement, when you attempt to access the workspace from the web UI, you are presented with the following dialog:
Security Question

Accessing workspaces with these options requires slightly different handling when working from the API. Before you can do anything with the workspace, you need to do the same basic things that the UI is doing. From the API side, to get started you first need to POST an empty workpsaceEntryRequest to the workspaces entry API like this:

V1 Version:

curl -X "POST" "https://test-api.intralinks.com/services/workspaces/entry?method=CREATE&client=<CLIENT_ID>&workspaceId=<WORKSPACE_ID>&httpStatus=T"
-H "Cookie: ssoGlobalSessionID=<session>"
-H "Content-Type: application/x-www-form-urlencoded"
--data-urlencode "xml=<workspaceEntryRequest></workspaceEntryRequest>"

V2 version:

curl -X "POST" "https://test-api.intralinks.com/v2/workspaces/{workspace_ID}/splash" \
    -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d $'{}'

This call will return a response identifying what you need to do next stored in the state parameter:

V1 API:

<workspaceEntryAuthResponse>
  <status>
    <code>201</code>
    <message>The entities have been created</message>
  </status>
  <state>ACCEPT_SPLASH</state>
</workspaceEntryAuthResponse>

V2 API:

{
  "status": {
    "code": 201,
    "message": "The entities have been created"
  },
  "state": "ACCEPT_SPLASH"
}

The possible states are: ALLOW BLOCK ACCEPT_SPLASH ONE_TIME_PASSWORD SECURITY_QUESTION CONTENT_DECLARATION_REQUIRED

For ACCEPT_SPLASH, you can make a second POST request with the acceptSplash parameter set to T.

For ONE_TIME_PASSWORD, you make the next POST request with the oneTimePassword parameter set to the password that was mailed to the user immediately upon the previous API request.

For SECURITY_QUESTION, you make the next POST request with the answer parameter set to the answer to the user's security question. The question that needs to be asked is specified in the securityQuestionKey parameter in the response. To get the list of security questions themselves, you can call the Get Challenge Questions API

For CONTENT_DECLARATION_REQUIRED you must identify what level kind of content you want to work with. There are some workspace settings that enable what is called 'Public vs Private' content. If the workspace has this turned on, the first time you enter the workspace you need to pass this choice in an additional object in the request in the form of a contentDeclarationUpdateRequest. Please refer to the enter workspace api documentation for more details.

Keep in mind, with both password and challenge questions, the response will also include the numOfAttempts parameter. This keeps track of how many invalid attempts at entering the workspace you have made, and after 3 failed attempts the system locks the user out and they will have to use the UI to reset their password. If the user is in this state, the STATE parameter will be set to BLOCK.

With each successful call to the entry API, you need to add the infomation to the request; each response will contain an updated STATE parameter. If additional info is required, you simply need to make repeated POST calls to the entry API and supply the additional information requested. NOTE: each call adds information to the previous request. So if the workspace has a splash screen, challenge question, and one-time password, you need to make 4 total calls to the entry API and each time add the newly requested data from the user with each request. The final request in this example would look something like this:

V1 API:

<workspaceEntryRequest>
   <acceptSplash>T</acceptSplash>
   <answer>My Answer</answer>
   <oneTimePassword>PASSWORD</oneTimePassword>
</workspaceEntryRequest>

V2 API:

{
    "acceptSplash" : true,
    "answer" : "my answer",
    "oneTimePassword": "password"
}

Once this the entry API responds with a STATE value equal to ALLOW, you are officially into the workspace and free to make any other API calls to work with the contents.

Splash Screens

A final note about splash screens: If the workspace has a splash screen associated with it, you will need to use the acceptSplash options detailed above to “accept” the conditions displayed in the screen.
However, before you do that, if possible it is advisable to get the text and or image the owner of the workspace has set up and display it to the user. The conditions will be stored as an image, as text or as HTML and can be retrieved using the workspaces/entry API and by passing the splashReturn set to A. If the splash has an image associated with it, the hasImage will be set to T or splashURL will be set to the URL of the image. If hasImage is true, you can use the splashImage API to download the image itself.

Related tasks:

V2: Enter Workspace List Workspaces List Documents

V1: Enter Workspace List Workspaces List Documents I