Using Trillo Workbench APIs

In previous chapter we saw an introduction of Trillo Workbench. This chapter introduces how to use Trillo Workbench APIs.

Using Trillo Workbench as a service (restful) is a two step process.

1. Obtaining access token.

2. Invoking API - by passing access token (bearer) as Authorization header.

Obtaining Access Token

Trillo Workbench uses a token obtained using login or OAuth2 credentials. These options are described below in detail.

Obtaining access token during login

A user's application such as web or mobile UI obtains access token during login (authentication flow). During this process the user establishes own identity. Trillo Workbench supports following options - 1) Trillo Workbench acts an identity provider, 2) Trillo Workbench uses external identity provider through OIDC to acquire an access token.

Trillo Workbench as a Identity Provider

Trillo Workbench has a built-in authentication. In this scenario, WB acts as a service provider and authentication service. This is suitable when an enterprise identity services such as Active Directory, Okta, OneLogin are not available. This may also be useful during early development of an application.

The following example shows how to use Trillo Workbench API to get the authentication token.

Endpoint:

POST /_preauthsvc/user/authenticate

Headers:

'Content-Type':'application/json'

Body:

{
  "userId": "[e-mail]",
  "password": "<password>"
}

Response:

{
  "access_token":"<access toke value>",
  "token_type": "bearer",
  "expires_in":3600,
  "refresh_token":"<refresh token value>",
  "scope": "comma separated list of roles"
}

External Service as an Identity Provider

Trillo Workbench supports integration with OIDC compliant identity providers such as Okta, OneLogin, Active Directory, Google Cloud Identity, etc. It uses authorization code grant.

See a chapter on OpenID Connect (OIDC) for Identity below. It discusses:

1. How to configure information of the external identity provider in Trillo Workbench.

2. API used by the client program to initiate authorization grant flow.

3. An API used to exchange nonce for the access token (between client and Trillo Workbench, for reference API path is /_oauth2/nonceLogin).

In future, Trillo Workbench will support SAML for external identity integration. Contact us for SAML support. It is in our product roadmap. We can accelerate if your use case depends on it.

Obtaining access token using server to server communication

The previous section describes the process where a client obtains an access token from the Trillo Workbench. This section describes the process when another server can obtain access token from the Trillo Workbench. Trillo Workbench supports following OAuth2 grants for server to server authorization.

1. Client credentials grant

2. Password grant

In order to use either of grants, you need to generate credentials using Trillo Workbench UI. See the section Settings > API Credentials for more details. Once you acquire the credentials, use the following APIs to obtain access token for API calls.

Client credential grant

The following code shows an example of the client credentials grant. This grant is less secure compared to authorization code grant discussed above. It is generally preferred when two applications are trusted, preferably within the same firewall or the data is very sensitive.

Endpoint:

POST /oauth/token

Headers:

'Content-Type':'application/json'

Body:

{
  "grant_type": "client_credentials",
  "client_id": "<client id value>",
  "client_secret": "<client secret value>"
}

Response:

{
  ... same format as the example above ...
}

Password grant

The following code shows an example of the password grant. This grant is equivalent to the client credentials grant except that it provides for resource owner credentials (username, password). Since it is unlikely that the client application will have access to the actual password of the user, these parameters do not have more significance than another set of credentials.

Endpoint:

POST /oauth/token

Headers:

'Content-Type':'application/json'

Body:

{
  "grant_type": "password",
  "client_id": "<client id value>",
  "client_secret": "<client secret value>",
  "username": "[e-mail]",
  "password": "<password>"
}

Response:

{
  ... same format as the example above ...
}

Invoking API

Once an access token is obtained using one of the methods described in the previous section, a client can exercise APIs of Trillo Workbench by passing access token in the header. The following is an example of a Trillo Workbench API, to retrieve a signed URL.

End-point:

POST /foldersvc/cloudstorage/folder/retieveSignedUrl

Headers:

The following headers are added to all Trillo Workbench APIs. "Authorization" header is required for all APIs except APIs discussed here (to obtain access tokens).

'Authorization':'Bearer ' + '<value of the access token'
'Content-Type':'application/json'

Note the space after Bearer.

Body:

{
   “folderName” : <cloud storage bucket folder>,
   "subFolder":  "<sub folder if any>",
   “contentType” :<file content type>,
   “fileName” : “<name of the file to be uploaded>,
   “method”: “PUT”
}

The parameter “method”: “PUT” above is a parameter to the signed URL. 
It does not imply an HTTP method. It instructs Google Cloud Storage service
to return a signed URL, which can be used for upload.

Response:

{
    “code”: 200,
    “data: {
       “signedUrl” : “value of signed URL”
    }
}