Help Page Home - Authentication

Authentication and Authorisation

The Saasu API supports 2 forms of authentication, namely authentication keys and OAuth 2. Authentication keys are what were used in older versions of Saasu API are are still supported but will eventually be phased out in favour of OAuth 2.

Authentication keys (wsAccessKey and FileId)

This method of authentication has been in use in the Saasu API since its inception and requires the specification of the following query parameters:

wsAccessKey This is an access key generated by the Saasu application and can be retrieved by going to the 'Settings - Web Services' option in the Saasu web application.
FileId This is the Id of your file you are trying to access via the API can be retrieved by going to the 'Settings - Web Services' option in the Saasu web application.

For example, https://api.saasu.com/contacts?wsAccessKey=34A88520A8244D2FA1DBFECC34677E3B&FileId=12345

Please note:This authentication mechanism will be phased out sometime in the future.

OAuth 2 Authentication flow

OAuth 2 basic authentication flow requires that you first obtain an access token and a refresh token. Once these are obtained you then only need to use the dynamically generated access token to access the API. Periodically, this access token will expire and you will use the refresh token to obtain a new access token, and continue using the API.

Grant types, access tokens and refresh tokens

The OAuth 2 specification (full specification here) lists various grant types that can be used to obtain an access token. Currently the Saasu API only supports the password credential grant (Details here)

Password credential grant flow

If using the Saasu supplied .Net client, this flow is taken care of for you, however other clients will need to implement this flow to be able to use OAuth 2.

The client must first issue a HTTP POST to https://api.saasu.com/authorisation/token which contains the following content in the body: "grant_type": "password", "username":"johndoe", "password":"ABC123", "scope":"full" so that the entire post looks something like

                         POST /token HTTP/1.1
                         Host: api.saasu.com
                         Content-Type: application/json

                        {  
                          "grant_type":"password",
                          "username":"username@test.com",
                          "password":"password",
                          "scope":"full"
                        }

Assuming the client is authenticated correctly with the username and password, then the server responds with a the data corresponding to an access_token, refresh_token, and expires_in values similar to what is shown below

                         HTTP/1.1 200 OK
                         Content-Type: application/json;charset=UTF-8
                         Cache-Control: no-store
                         Pragma: no-cache
                         {
                           "access_token":"2YotnFZFEjr1zCsicMWpAA",
                           "token_type":"example",
                           "expires_in":3600,
                           "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
                           "scope","FileId:12345 FileId:65432 FileId:98765"
                         }

The client can then use the access_token in subsequent requests to the API by embedding the access token into each HTTP request using the Authentication header and the Bearer identifier to signnify a token type as shown in the example below.
```
                         GET /contacts HTTP/1.1
                        Host: api.saasu.com
                        Authorization: Bearer yourAccessTokenGoesHere
                    
```
The access token will typically expire in a short time as indicated by the expires_in parameter in the initial grant request. This parameter is an indicator in seconds, of when the access token will expire. The client can either wait for the token to expire, or pre-emptively request the access token be refreshed by issuing a HTTP POST request to authorisation/refresh endpoint and specifying a grant_type of refresh_token and a parameter of refresh_token with the actual refresh token originally issued (note that the refresh token will expire after 12 months). This is shown in the example below:
```
                         POST authorisation/refresh HTTP/1.1
                         Host: api.saasu.com
                         Content-Type: application/json
                         {  
                          "grant_type":"refresh_token",
                          "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}                        }
                    
```
This will return the same response as the initial access token request.

Scope

OAuth 2 also supports the notion of a scope parameter when making the initial grant request. Currently Saasu API does not support any incoming scope parameters but may do so in the future.

Saasu does return the list of file id's that the user has access to via the scope when returning the response to the intial grant request. The file id's will be space separated as part of the scope value as shown in the following example:

                    HTTP/1.1 200 OK
                    Content-Type: application/json;charset=UTF-8
                    Cache-Control: no-store
                    Pragma: no-cache
                    {
                    "access_token":"2YotnFZFEjr1zCsicMWpAA",
                    "token_type":"example",
                    "expires_in":3600,
                    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
                    "scope","FileId:12345 FileId:65432 FileId:98765"
                    }