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 Account Management REST API

To use the Account Management REST API, you must establish a user session by requesting an authentication token. The authentication token must be used 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 Account Management REST API you must have the following:

  • An installation of Platform version 6.6.0 or later
  • A valid username and password to the Platform
  • Be assigned to an active Tenant Account or Developer Team and know the tenantAlias or devTeamAlias. See how to get your tenantAlias/devTeamAlais.

Authentication URL

Account users can make a REST call from any client to the JSON authentication URL for their target Platform instance. In the URL below, your Platform URL for the cloud you wish to connect to should replace CloudURI. See more information on where to find your CloudURI.

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

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. You must also include the Tenant alias for the Tenant account you want to connect under.

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/account

Request Body

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

If the request is successful, the Platform will return an object with an authentication token and URL of the user session. The value of ApprendaSessionToken in the response body is your authentication token to be used in all future requests to the Account Management 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 Body

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

}

User Sessions

Once created, users can make requests to the Account Management 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/account/{ApprendaSessionToken}

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

Example Request

Verb: DELETE

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

Getting the Tenants of a User

The REST API can also be used to retrieve a list of tenants (or Dev Teams) through which a User has been granted a subscription for a specified application. Here is an example that assumes a CloudURI of “http://apps.apprenda.harp” and an {appAlias} of “account”:

Example Request

Verb: GET

URL: https://apps.apprenda.harp/authentication/api/v1/sessions/account/tenants?username=myemail@mycompany.com&password=password

Response Body

{
"tenants": [
    "devteam1",
    "devteam2"
    ]
}