OAuth Access Tokens and Authentication

Your request to the Work Unit API must authenticate using an active OAuth access token, provided by ATPCO. Access tokens typically expire after one hour.

Note: Each organization will be issued authentication information (sent separately) that must be used to get an OAuth token from ATPCO.

OAuth Access Token

The below information explains how to get an OAuth Access Token by way of example using Spring Framework’s RestTemplate class.

Prerequisites

Any API consumer seeking an OAuth Access Token must already have the following:

client_id – an ID assigned to you by ATPCO (e.g., ABC3DEF)
client_secret – a key (secret string of characters) provided by ATPCO when you were authorized to access ATPCO APIs

attention

If you are missing your client_id or client_secret, please contact ATPCO Support.

Get an OAuth Access Token

The following example uses Spring Framework’s RestTemplate class to request an OAuth Access Token from ATPCO:

Copy

Copied

RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();

// The request header content type must be FORM_URLENCODED
// as though the request were coming from a submitted HTTP form

headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
MultiValueMap<String, String> map = new LinkedMultiValueMap<String, String>();

// We pass the “client_id” and “client_secret” in a map

map.add("client_id", "<client id given by ATPCO>");
map.add("client_secret", "<client secret given by ATPCO>");

// The “grant_type” must be set to “client_credentials”

map.add("grant_type", "client_credentials");

HttpEntity<MultiValueMap<String, String>> httpEntity = new
HttpEntity<MultiValueMap<String, String>>(map, headers);

// We call the OAuth service using the RestTemplate’s postForEntity

ResponseEntity<AccessTokenInfo> response = restTemplate.postForEntity(
<OAuth Token Request URL>, httpEntity , String.class );

// The <OAuth Token Request URL> should have been sent along with the client_id
// and client_secret – please contact ATPCO Support if you don’t have the URL

If the above request succeeds (i.e., the OAuth Token Request URL, client_id, and client_secret are all correct), the response will include a JSON object like the one below:

Copy

Copied

{
"access_token": "Unu42cvJomRGEW7Zylp7Uy4r8yOZbttazi077Zn8sYzPMUEVr20zdF",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "rec3rules.READ rec3rules.WRITE"
}

The value of the “access_token” key is your OAuth Access Token.

Copy

Copied

response.getAccess_token(); // use this method to get the OAuth Access Token

Authenticate Your ATPCO API Call

The below information explains how to use an OAuth Access Token to authenticate an API call, by way of example using Spring Framework’s RestTemplate class.

Prerequisite

Any API Consumer looking to call an ATPCO API must already have an OAuth Access Token. This is a string provided by ATPCO that temporarily grants you access to ATPCO APIs.

attention

If your OAuth Access Token has expired, you must obtain a new OAuth Access Token.

Authenticating

The header of your API request must have a content type of "application/json" or "application/xml" (depending on the API) and must include the following two parameters for authentication:

Parameter	Description	Type	Format
Authorization*	A valid OAuth access token, issued by ATPCO, prepended with "Bearer" (including the space)	String	“Bearer <OAuth access token>”
userId*	The ATPCO user ID to authorize data access for this service call	String	“XXX#XXX”

*required parameter

The below code snippet demonstrates one way to construct a request to ATPCO APIs with an OAuth Access Token. This example uses Spring Framework’s RestTemplate class to request an OAuth Access Token from ATPCO:

Copy

Copied

RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();

// Set up header content-type and parameters
// Note: some APIs use XML instead of JSON
// Check the documentation for the API you intend to call

headers.setContentType(MediaType.APPLICATION_JSON);
headers.add("Authorization", "Bearer <OAuth access token>");
headers.add("userId", "<user id>");

MultiValueMap<String, String> map = new LinkedMultiValueMap<String, String>();

HttpEntity<MultiValueMap<String, String>> httpEntity = new
HttpEntity<MultiValueMap<String, String>>(map, headers);

ResponseEntity<String> response = restTemplate.exchange("<API URL>", HttpMethod.GET,
httpEntity, String.class);

// Note: <API URL> is the URL to access the API you are calling
// Note: In this example of a GET method call, the API URL would include the request
parameters in the URL query string
// (i.e., developer.atpco.net/PATH/?key=value&...)
// Please contact ATPCO Support if you don’t have the URL