If you are new to developing API integrations, you may want to start by reading our Examples of Authorisation and use of the Actionstep API in the staging environment using Postman.

Please note: there are two domain names here, api.actionstepstaging.com and ap-southeast-2.actionstepstaging.com. The first (api) is used for all oAuth2 requests (create token, renew token etc) and ap-southeast-2 is where all the JSON:API calls are made. Note that this second url is dynamic and should be fetched from the JSON data in the access token response. While it is generally static in our staging environment, it will be dynamic in production as different organizations are stored in different regions.

STEP 1: Authenticate The User

Your app must direct the user to an Actionstep login page to authenticate themselves. We will then send you back an authorization code which you can use to request an access token. You will then use the access token to exchange data with the Actionstep API. For security reasons the access token only lasts for about an hour and then you need to refresh it. When you request your access token for the first time we will return the access token along with a "refresh token". We will also tell you how long the access token is good for. You can use the refresh token to request a new access token when required.

Authorization Code: We will send this to you once the user has logged in successfully. Use this to request an Access Token.

Access Token: Use this to communicate with the API

Refresh Token: Use this to get a new Access Token when it expires

Get an Authorization Code

Send the user to

https://go.actionstepstaging.com/api/oauth/authorize?response_type=code&scope=________&client_id=______&redirect_uri=________

Fill in the blanks with your details:

scope: what data you wish to access (actions, participants, etc). If specifying more than one then use a SPACE character to separate them e.g. "scope=actions timerecords participants"

client_id: provided to you by Actionstep

redirect_uri: where we should send the user after they have authenticated themselves.

Once authorized we will send the user back to your redirect_uri and add a code=xxxxx parameter to the end of the URI. You need to grab that code and use it to request the access token

Remember to encode the url so that spaces and other special characters are escaped

Get an Access Token

Send a POST request to https://api.actionstepstaging.com/api/oauth/token with the following parameters:

code: the authorization code obtained above

client_id: same as above

client_secret: same as above

grant_type: authorization_code

redirect_uri: same as above

If successful you will get a JSON response containing access_token, refresh_token, expires_in, token_type, api_endpoint

Save this information and make a note of when the access token expires so you know when to refresh it.

STEP 2: Send and Receive Data via the API (the fun bit!)

Refer to the rest of the API documentation for the details, but it's all a variation on the same basic theme.

Get Some Data

Use a GET request with no parameters (the access token is included in the HTTP headers).

For example, to get a list of Actions:

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

Include the following HTTP headers:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Authorization: Bearer __________

Do not terminate the URI with a slash
The URI does not include the "fe-" prefix
Add your Access Token after "Bearer"
Leave one space character between "Bearer" and your Access Token

If successful you will get a JSON response containing the data you requested.

The production endpoint is dynamic. You need to use the api_endpoint property from the token response when building the url for resource requests: api_endpoint + "rest/" + resource

Create Some Data

Send an HTTP POST with a JSON payload.

For example, to create a new File Note send a POST to

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

with a JSON payload something like:

{
	"filenotes": {
		"text": "My Awesome New File Note"
		"links": {
			"action": 9
		}
	}
}

And include the usual HTTP headers:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Authorization: Bearer __________

STEP 3: Refreshing your Access Token

If your Access Token has expired (or is about to) you can refresh it by sending a POST request to https://api.actionstepstaging.com/api/oauth/token with the following parameters

refresh_token: the refresh token obtained when you received your first access token above