Authentication using OAuth

Workspaces OAuth lets users allow other applications to interact with their Workspaces account without providing that other application their Workspaces authentication credentials, and for only a time-limited basis. For example, a sales management application can integrate Workspaces functionality to allow the controlled sharing of documents via Workspaces, within the sales management app, without requiring users to provide their Workspaces usernames and passwords to the sales management app.

Registering a client with a Workspaces server

Someone wishing to use Workspaces OAuth must register with Workspaces and obtain a client ID and client secret that will be passed to Workspaces in order to obtain a Workspaces authentication token.

Authenticating using StartSessionWithOAuth

The StartSessionWithOAuth method in ApiSession provides an easy way to authenticate users using OAuth. After creating an instance of ApiSession and making a call to the StartSessionWithOAuth method, a window will appear to accept the authentication credentials for the user. This window will remain visible until the user successfully authenticates with the Workspaces server or the user closes the window. Because of this the StartSessionWithOAuth method is a blocking call. Once the user has provides their credentials correctly or closes the window the LoginResult value is returned from the method. If the user provided a correct set of credentials the StartSessionWithOAuth method returns a "Success" LoginResult.

Copy

ApiSession apiSession = new ApiSession(serverUrl);
LoginResult loginResult = apiSession.StartSessionWithOAuth(email);

Manually authenticating using OAuth

The basic flow is as follows where WORKSPACES_URL refers to the base URL of the Workspaces server being used:

Make an unauthenticated call to WORKSPACES_URL/api/3.0/authentication/parameters to get the authentication URI's. In the returned values, authorizationUri is the URI for the temporary token in #2 below; accessTokenUri is the URI for obtaining the full token in #4 below.
Direct the user to the Workspaces authenticationUri (e.g. via a redirect in your own web app), passing the proper params(see below). One of these params is the redirect URI in your app to which the user should be sent after authenticating with Workspaces. It will look something like this (wrapped across lines here, but one single line when used):
Copy
```
<WORKSPACES_URL>/<AUTHORIZATION_URI>?response_type=code&client_id=<CLIENT_ID>&locale=en_US
&redirect_uri=<REDIRECT_URI>
```
When that redirect URI is serviced in your web app, a temporary code is included on the URL that will be used to obtain a valid auth token. It will look something like this:
Copy
```
<REDIRECT_URI>/?code=219e5a32-d74f-473a-91a4-fd74f95e091c&locale=en-us
```
Make a call to the Workspaces accessTokenUri to obtain a valid auth token, refresh token, and an expiration value for the auth token. That auth token can be used to authenticate subsequent API calls to the Workspaces server (wrapped across lines here, but one single line when used).
Copy
```
<WORKSPACES_URL>/<ACCESS_TOKEN_URI>?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&
client_secret=<CLIENT_SECRET>&grant_type=authorization_code&code=<AUTH_CODE>
```
That call will return JSON that contains an access token, expiration, and refresh token. The access token can be used in the authorization header of subsequent calls.