Welcome to our docs site. Docs on this site are for ACP version 9.
See these links for previous versions: Version 8, Version 7

Authentication for the Platform Operations REST API

To use the Platform Operations REST API, you must establish an user session by requesting an authentication token. The authentication token is sent in all future requests during the user’s session. This page outlines authentication prerequisites, how to get an authentication token, and how to end a user session.

Prerequisites for Authentication

To make calls to the Platform Operations REST API you must first meet the following prerequisites:

  • A valid username and password to your Apprenda environment.
  • If System Operations Center (SOC) authentication is enabled, your account needs to be designated as a Platform Operator to access the Platform Operations REST API. See more about managing SOC access.

Authentication URL

Platform Operators can make a REST call from any client to the JSON authentication URL for their target Apprenda instance. Replace CloudURI in the URL below with your Apprenda environment URL for the cloud you wish to connect to.

[CloudURI]/authentication/api/v1/sessions/soc

Regardless of whether your CloudURI uses http or https, all requests made to the JSON authentication URL should be done through https.

Establishing a User Session

To get an authentication token, make a POST request with your username and password JSON-formatted in the body of the request.

The example below illustrates making an authentication request. The example assumes a CloudURI of “http://apps.apprenda.harp” and specifies “Content-Type: application/json” in the request header.

Example Request

Verb: POST

URL:* https://apps.apprenda.harp/authentication/api/v1/sessions/soc

Request Body

{
  "username" : "myemail@mycompany.com",
  "password" :  "password"
}

If your request is successful, the Platform will return a JSON object with your authentication token and url of the user session. The value of ApprendaSessionToken in the response body is your authentication token to use in all future requests to the Platform Operations REST API. This token must be passed with any future requests you make during this session. It can be passed in POST or PUT requests as JSON in the body of the request, or as an HTTP header called ApprendaSessionToken (not case sensitive).

Successful Response

{
  "ApprendaSessionToken" : "MWM1ZDQ5ZDAtODk1My00OTQ1LWJhYjctYTEzN2JmZGZjOGZhfDAwM2Q1MTc5LWM4ZDktNGYwYy1hOWRlLThhZTM3N2JjODQ1ZQ%3D%3D",
  "href" :  "https://apps.apprenda.harp/authentication/api/v1/sessions/soc/MWM1ZDQ5ZDAtODk1My00OTQ1LWJhYjctYTEzN2JmZGZjOGZhfDAwM2Q1MTc5LWM4ZDktNGYwYy1hOWRlLThhZTM3N2JjODQ1ZQ%3d%3d",

}

User Sessions

Once created, users can make requests to the Platform Operations REST API until the user session expires or is terminated. The length of a user session is configured by a Platform-wide default set by the Platform Administrator in the Platform Registry page of the SOC. It is recommended that all user sessions be terminated when you are finished making calls to the REST API. Instructions for terminating a user session can be found in the following section. Terminating a User Session

Terminate a user session by sending a DELETE request that specifies the ApprendaSessionToken for the user session being terminated.

[CloudURL]/authentication/api/v1/sessions/soc/{ApprendaSessionToken}

The example below assumes a CloudURI of “https://apps.apprenda.harp”

Example Request

Verb: DELETE

URL: https://apps.apprenda.harp/api/v1/sessions/soc/MWM1ZDQ5ZDAtODk1My00OTQ1LWJhYjctYTEzN2JmZGZjOGZhfDAwM2Q1MTc5LWM4ZDktNGYwYy1hOWRlLThhZTM3N2JjODQ1ZQ%3d%3d