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. |
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 |
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 |
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.
Refer to the rest of the API documentation for the details, but it's all a variation on the same basic theme.
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 __________ |
|
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 |
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 __________ |
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
client_id: same as above
client_secret: same as above
grant_type: refresh_token
redirect_uri: same as above
If successful you will get a JSON response containing access_token, refresh_token, expires_in, token_type, api_endpoint