Authentication and Authorization

Authentication and authorization in Actionstep use the OAuth2 protocol. If you are unfamiliar with this protocol or have not used it before we strongly recommend further reading before you start coding.

The Actionstep Security Model

Actionstep implements a user-centric security model. This means all interactions with the API are performed under the security context of a user granting your application permission to access data on their behalf. The access permissions granted to your application are identical to the access permissions granted to the user. The API does not provide a greater or lesser degree of data access than the authenticated user.

A key point to note is any restricted access that may be placed on some data items and areas of functionality to the authenticated user. Every API request is security validated against the user's permissions before being allowed to proceed. Please endeavour to incorporate appropriate exception handling logic to handle being denied access to either data or functionality if the user does not have the required permissions.

One of Actionstep's key security features is the ability to mark a Matter as Restricted Access. This means only the creating user and other nominated users (granted by the creating user) will have visibility of a restricted access Matter. The API fully implements any restrictions imposed by the restricted access security model.

All activity an individual user performs in Actionstep is captured in the Session Activity Log for auditing purposes. The session activity log also includes all API related activities performed by your application under the security context of the authenticated user.

Definitions

The terms authentication and authorization are often confused and taken as meaning the same thing. They are in fact two very distinct steps in a process of enabling access to a system.

Authentication

Is the process of proving who you are to a system or third party. Actionsteps's login process is an example of an authentication process. The login form asks you to provide two pieces of personal information about yourself (your credentials). Actionstep performs a number of checks to verify these credentials are correct and that you are known to Actionstep.

Authorization

Is the process of determining what you can do and what you can see. Once you have logged in, Actionstep will determine the functionality available to you by checking the permissions associated with your account. It enables Actionstep to present you with the information you are authorized to view, and to access functionality you are authorized to use, both of which are determined by the permissions associated with your account. Your System Administrator is responsible for managing user accounts and permissions within your organisation.

The OAuth2 Flow

Steps

1. The user is redirected to a login page to authenticate as a valid user.
2. Upon a successful login the Authentication Server will return an authorization token.
3. The authorization token is presented to the Authorization Server and validated.
4. The response from the Authorization Server is an access token and a refresh token.
5. An API request is made to the API Server and includes the access token as a request header.
6. The requested data is returned from the API Server to the user.

The Authorization Server also performs the role of refreshing an access token. In this case the Refresh Token obtained in step 4 is presented to the Authorization Server and a new Access Token is returned.

Actionstep's implementation of OAuth2 involves the following steps:

Step 1 - Obtain an Authorization Code (Token)

In the first step your application needs to authenticate the user with Actionstep. This is achieved by redirecting the user to the Actionstep login page from where the user enters their email address and password (their personal credentials). The redirection must include a number of parameters including the Client ID from your API Credentials, the requested scopes (space separated if specifying multiple scopes), and the return uri (callback) to transfer control back to your application. The response sent back from the Authentication Server will be an authorization code.

NB: Don't forget to url encode the callback uri.

https://go.actionstepstaging.com/api/oauth/authorize?response_type=code&scope={scopes}&client_id={ClientId}&redirect_uri={redirectUri}

If Multi-factor Authentication (MFA) is enabled an additional screen is displayed asking the user to enter a MFA code.

The user will then be asked to grant your application access to their Actionstep account as shown in the following screen shot:

The redirect uri you specify will be called by Actionstep and the authorization code appended to the end of the request, for example:

https://www.myorganisation.com/mymethod?code=b3b62e5a9421a92a25d1bb558f02438d7eaf7c99

Step 2 - Obtain an Access Token

The next step is to use the authorization code obtained from the first step to obtain an access token. It is the access token you need to include with every call you make to the Actionstep API. To get an access token make a POST request to the following uri:

https://api.actionstepstaging.com/api/oauth/token

The request body should contain the following parameter key/value pairs:

Parameter Name	Parameter Value
code	The authorization code obtained from Step 1.
client_id	Your Client ID from your API Credentials.
client_secret	Your Client Secret from your API Credentials.
grant_type	The grant type, which is a fixed value and should be set to the constant "authorization_code".
redirect_uri	The same redirect uri used in Step 1 (but note its not actually called).

The response is a JSON structure containing the following key/value pairs:

Property	Value
access_token	The access token to use in all API requests.
token_type	This will be set to "bearer".
expires_in	The number of seconds the access token will expire in.
api_endpoint	The endpoint to which you direct all Actionstep API requests.
orgkey	Your unique organisation key.
refresh_token	The refresh token used to obtain a new access token.

Example JSON response:

{
    "access_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.....XSIJZVwiqCyT2U-6AyLAgfiQfIK75wojjvPjqYkQNQ",
    "token_type": "bearer",
    "expires_in": 28800,
    "api_endpoint": "https://ap-southeast-2.actionstepstaging.com/api/",
    "orgkey": "legalES",
    "refresh_token": "NDJkNjVhMmVkNzE1MWI4ZjNiMTlmMzEyYmQ2ZGQ3NzBhYjYxMGRkMjlhMTAw"
}

NB: The access_token is considerably longer than shown, having been abbreviated for brevity.

NB: Once successfully authenticated please ensure you use the returned api_endpoint property as the base URL when constructing all API requests. Each geographical region in which Actionstep operates has a different base URL and may change in the future, so using the api_endpoint property will assist in future-proofing your solution.

NB: In addition, ensure all requests are prefixed with "rest" in the URL path, for example:

https://ap-southeast-2.actionstepstaging.com/api/rest/actiontypes

Refreshing Your Access Token

Every access token has a finite lifetime for security purposes. Periodically you will need to obtain a new access token to continue making calls to the Actionstep API. You can either refresh your access token after it has expired or pre-emptively based on some other criteria, for example, within 60 seconds of the access token expiring. To refresh your access token make a POST request to the following uri and specify the following values in the request body:

https://api.actionstepstaging.com/api/oauth/token

Parameter Name	Parameter Value
refresh_token	The refresh token obtained from the previous request for an access token.
client_id	Your Client ID from your API Credentials.
client_secret	Your Client Secret from your API Credentials.
grant_type	The grant type, which is a constant and should be set to "refresh_token".
redirect_uri	The same redirect uri used in Step 1 (but note its not actually called).

Example JSON response from refreshing the access token:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.......EcfoIdjpVy-UV1aIAYFHgQhM_PfSg",
    "token_type": "bearer",
    "expires_in": 28800,
    "api_endpoint": "https://ap-southeast-2.actionstepstaging.com/api/",
    "orgkey": "legalES",
    "refresh_token": "OWFjYTExZDk1OWFmNjU4YjNjOGFmZjE2MDhiMzJhNjQ1MTBlNTk5OTExODhl"
}

Using Postman to Refresh your Access Token

During development and testing with Postman you will likely at some point need to refresh your access token. You can either choose to simply re-authenticate (login again to Actionstep) or you can refresh your access token as described above. When refreshing your access token using Postman its important to highlight the need to choose the correct body encoding. You need to ensure the encoding is set to x-www-form-urlencoded as shown in the image below.

Development Urls

Endpoint	Url
Authorize	https://go.actionstepstaging.com/api/oauth/authorize
Access Token	https://api.actionstepstaging.com/api/oauth/token

Production Urls

Endpoint	Url
Authorize	https://go.actionstep.com/api/oauth/authorize
Access Token	https://api.actionstep.com/api/oauth/token

Commercial Application Development

If you are building a commercial application the above OAuth authentication process still applies since it is a client driven workflow. The only difference is that you will be using your ClientId and ClientSecret to initiate API calls on behalf of all your customers that grant your application rights to access their data. When storing your ClientId and ClientSecret in configuration files we recommend doing so in encrypted form. We also ask that you make it clear to your customers the data you will be accessing in Actionstep (scopes), how the data will be processed, and how you will provide support to your customers.

The access token typically expires in 28800 seconds (8 hours) and the refresh token has a current lifetime of 21 days. So while in effect you can create a perpetual connection we advocate periodically requesting your customers reauthenticate their access to Actionstep from a best practice and data security standpoint.

NB: When building multiple commercial applications you are required to obtain a set of Production API Credentials for each unique application. Each application will be subject to its own API Review.

Sample Source Code

Actionstep has built a demonstration application that implements many of the commonly used API requests including the authentication and authorization process.

You can discover more about the application here, or check out the Actionstep GitHub repository.