Authentication

The first step in integrating with the STACK API is understanding the API’s authorization process. Any time a Partner makes a request to the STACK API, whether on behalf of the Partner or on behalf of a User affiliated with a Partner, they must be authorized through STACK’s Authorization Server.

OAuth 2.0 – Two-Legged Authorization
OAuth 2.0 – Three-Legged Authorization
Token Expiry

OAuth 2.0 - Two-Legged Authorization

Two-Legged authorization is used when your integration is writing data into or reading from an account that you control. This is typically server-to-server communication where you may create Project, Plans, Files directly into your own account.

Obtaining Client Credentials

STACK will provide a Partner with their own clientId and client secret, together these are the API Credentials. The clientId and client secret are combined, separated by a colon and base64 encoded as follows:

Combine the clientId and client secret: ex. “5:11728663-C8DD-4B84-9B2B-4E3916631A54”
Ensure that the “clientId:client-secret” are Base64 Encoded.

Add the encoded client credentials to the Authorization Header of the request:

Authorization: Basic
NToxMTcyODY2My1DOERELTRCODQtOUIyQi00RTM5MTY2MzFBNTQ=

Obtaining an Access Token on Behalf of the Partner

To obtain an access_token, a Partner must make a POST request to this endpoint: “https://{server}/OAuth/Token” and include the Client Credentials in the Authorization header of the request. Replace {server} with the sandbox server URL provided along with your API credentials. A Grant Type is also required in the body of the request; “grant_type=client_credentials”.

Request:

POST https://{server}/OAuth/Token
Authorization: Basic
VEhJUyBJUyBCQVNFNjQgU1RSSU5HIE9GIFlPVVIgUEFSVE5FUklEfFBBUlRORVIgU0VDUkVU
Cg==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials

Note there must be no line endings after the form data, if an invalid grant_type will be returned. This includes carriage returns (0x0d) and or new lines characters (0x0a).

Response:

{
“access_token”:
“tG05IRnPA3hBINzKmIU28zR60xqoachJzI5av5RMTeCRE8uNzeYt95w9XOmNon-4lF3KXQj
gakNfMT9nHgtRxItobmdkZ4xi849LlMhS6SKyCQvHI….”,
“token_type”: “Bearer”,
“expires_in”: 28799,
“refresh_token”:
“898c0a5d1a5c42a9898caf23de67467847db7c42e53f4aa8b599eadc495c55e4”
}

Note the access_token in the response. The access_token will be used in the Bearer Authorization Header of any future requests to the API. access_tokens will expire as shown in the expires_in field of the response and will need to be refreshed using the refresh_token.

Field Details:

Field Name	Type	Length	Purpose
access_token	string	2048	The access_token will be used in the Bearer Authorization Header of any future requests to the API. access_tokens will expire as shown in the expires_in field of the response and will need to be refreshed using the refresh_token. The length of the field may vary over time so you will experience strings around 1030 bytes but be sure to reserve 2048 bytes in any table column you store it in.
token_type	string		Always "Bearer" indicating that this is how you are to use this token.
expires_in	int		The number of seconds that this token is valid for.
refresh_token	string		After expires_in seconds this refresh_token can be used in another API call to retrieve another access_token.

Authenticating Requests to the API

Below is a sample POST to create a Project using STACK’s API:

Request Headers:

POST https://{server}/api/v1/Projects HTTP/1.1
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
…

See API Reference doc for request detail.

Refreshing Access Tokens

As mentioned above, access_tokens will need to be refreshed. The process is similar to initially obtaining an access_token. Use your Client Credentials in the Authorization header and format your refresh_token as shown in the example below.

Request Header:

POST https:// {server}.net/OAuth/Token HTTP/1.1
Authorization: Basic (your Client Credentials)
Content-Type: application/x-www-form-urlencoded
refresh_token=d826c4204c847bf63a16d271adea23e…&grant_type=refresh_token

Note there must be no line endings after the form data, if an invalid grant_type will be returned. This includes carriage returns (0x0d) and or new lines characters (0x0a).

Response:

{
“access_token”:”qKDJ5M7LPX-Do3aPCsaIrRzJ1_wsVt_6Whm2dMAkeMYTs1S5uQe…..”,
“token_type”:”Bearer”,
“expires_in”:28799,
“refresh_token”:”b368fd873df3406cb5b35482f68eb1597111ed851cf243df9edeb5e7e52ee4dc”
}

OAuth 2.0 - Three-Legged Authorization

Three-Legged authorization is used when your integration is writing data into or reading from an account on behalf of a user. This requires the user to grant your integration permission to control his or her data. Your application will request to control a user’s account and he must click a button to grant your application the appropriate permissions.

Obtaining Authentication on Behalf of the User

The following will describe how to authorize accessing the API on behalf of a User. The idea is that one of your customers is interacting with your product and you wish to transfer them to STACK. You will already have an access token from the two-legged workflow above so now you have to gain access for your user.

First, the user must be redirected to STACK’s Authorization Page. This can be accomplished by a redirect url applied to an action the User initiates such as clicking a link on the Partner’s page to view a Project in the STACK Application. The redirect will contain the redirect_uri provided by the Partner and the ClientID provided by STACK:

Request:

https://{server}/OAuth/Authorize?client_id=(your
ClientId)&redirect_uri=(your redirect_uri
encoded)&state=partner-created-value&response_type=code

The ClientID is the ID that STACK provided for you for your Client Credentials.

The redirect_uri is the uri you provided to STACK and is saved in STACK’s database as part of your Partner information. When sent in the query string, the uri must be encoded.

Example:

http%3A%2F%2Fyour%2Fredirect_uri.com

The state parameter is generated by the Partner for the Partner’s use.

The response_type=code part of the query string tells the STACK Authorization Server that you are requesting a one-time-use code (GUID generated by the Authorization Server) to be used to obtain an access_token for your User.

This is an example of what the user will see generated by the STACK Authorization Server

Once the User grants the Partner access by clicking the “Grant” button, the User will be redirected to the Partner’s redirect_uri and the one-time-use code will be specified in the query string. The query string returned should look like the example below:

Example:

http://your/redirect_uri/?code=7d07711d50c14cfeb0759d262878b03b37c50b063
5614ee8893a166e526da90b&state=partner-created-value

Note the state parameter returned is the same value that was passed to STACK in the original request. The code provided is a short lived and configured to expire in 5 minutes. If the user chooses to click the Cancel button, then a similar redirect will occur back to the Partner redirect_uri with error query string argument indicating the access denied.

http://your/redirect_uri/?error=access_denied&state=partners-unique-value

The customer expectation would be to be presented with the same Partner page that they used to launch STACK. The request for obtaining an access_token for a specific User can be made from the server and requires no additional action on behalf of the User. The request for obtaining an access_token for the User is similar to the request for obtaining an access_token for a Partner.

Request:

POST https://{server}/OAuth/Token HTTP/1.1
Authorization: Basic
VEhJUyBJUyBCQVNFNjQgU1RSSU5HIE9GIFlPVVIgUEFSVE5FUklEfFBBUlRORVIgU0VDUkVU
Cg==
Content-Type: application/x-www-form-urlencoded
code=7d07711d50c14cfeb0759d262878b03b37c5&state=partner-created-value&re
direct_uri=(your redirect_uri)&grant_type=authorization_code

Note there must be no line endings after the form data, or an invalid grant_type will be returned. This includes carriage returns (0x0d) and or new lines characters (0x0a).

Response:

{
“access_token”:”dfsahjaAsdYza1Rp6VSYwJ5M7LPX-Do3aPCsaIrRzJ1_wsVt_6Whm2d
MAkeMYTs1S5uQe…..”,
“token_type”:”Bearer”,
“expires_in”:28799,
“refresh_token”:”jfdkshfjdhs73df3406cb5b35482f68eb1597111e
d851cf243df9e deb5e7e52ee4dc”
}

Token Expiry

The authorization code, access token and refresh token all expire at different times. The table below explains the settings you should manage to:

Token Type	Expiry Time	Reason
Authorization code	5 minutes	This is a short-lived value, transmitted to the partner for immediate use to retrieve an access token.
Access token	8 hours	An access token, for two-legged or three-legged authentication, represents a logged in session only, and refreshed regularly to ensure the credential status hasn't changed.
Refresh token	90 days	This long period of time represents that the users granted permission is verified at a consistent frequency.

Authentication

OAuth 2.0 - Two-Legged Authorization

OAuth 2.0 - Three-Legged Authorization

Want to get more info on STACK's API connection?