Communicate with CSA

Solution developers communicate with CSA using HTTP or HTTPS and parse the data structures returned by CSA. The default port for communication is 8444.

Consumption API data is returned in JSON format. Legacy API data can be returned in either XML or JSON format. You must set the HTTP headers Content-Type:application/xml or application/json, and accept:application/xml or accept:application/json as appropriate for the call you're making.

Authentication with an integration account

Authentication is handled using HTTP basic authentication. The authentication value is provided to Legacy API calls and to the Consumption tokens API call via the basic authorization header.

When exercising an API call from the HTTP client or from the interactive API content, the authorization header is automatically generated. This authorization header is created using your CSA credentials that is required to get permission to make REST calls.

When exercising an API call from your application's code, you must create the authorization header. Supply the Base64 encoded value of the <username>:<password> string for the user you will use for authentication. The default credentials and authorization header for the Legacy and Consumption APIs are shown here:

API	Default user name	Password	Encoded credentials and authorization header
Legacy	csaTransportUser	Entered during CSA installation	Base64 encoded user:password: Y3NhVHJhbnNwb3J0VXNlcjpjc2FUcmFuc3BvcnRVc2Vy
			Authorization header: Basic Y3NhVHJhbnNwb3J0VXNlcjpjc2FUcmFuc3BvcnRVc2Vy
Consumption	idmTransportUser	Entered during CSA installation	This is used for the idm-service token call. Base64 encoded user:password: aWRtVHJhbnNwb3J0VXNlcjppZG1UcmFuc3BvcnRVc2Vy
			This is used for the idm-service token call. Authorization header: Basic aWRtVHJhbnNwb3J0VXNlcjppZG1UcmFuc3BvcnRVc2Vy

For information about managing built-in accounts, see the "Change CSA Out-of-the-Box User Accounts" section in the Cloud Service Automation Configuration Guide.

Consumption API authorization

Consumption API calls require an IdM authentication token. An authentication token is retrieved from the Identity Management component as demonstrated below. The Basic Authorization header as described in Authentication with an integration account is used to retrieve this token. The token.id value returned in the response body is the token you need to include in the X-Auth-Token HTTP header.

HTTP method	POST
Header	See header information that follows.
REST URL	https://<CSAFQDN>:<port>/idm-service/v2.0/tokens
Payload	{ "passwordCredentials" : { "username" : "consumer", "password" : "cloud" }, "tenantName" : "CONSUMER" }
Parameters	None
Request body	See example that follows
Response body	See example that follows
Returns	200 - success 400 - improperly formatted request body (most common cause is missing Content-Type header) 401 - missing or incorrect basic authentication information 403 - authentication failure 415 - missing Accept or Content-Type header, or one of these headers is not set to application/json

Header	Value	Meaning
Accept	application/json	Output is in JSON format
Content-Type	application/json	Input message body is in JSON format
Authorization	Basic aWRtVHJhbnNwb3J0VXNlcjppZG1UcmFuc3BvcnRVc2Vy	Default authorization header as described in Authentication with an integration account Base64 encoded value for idmTransportUser:<idmTransportUser password>

Example JSON request body:

{
   "passwordCredentials" : {
   "username" : "consumer",
   "password" : "cloud"
  },
    "tenantName" : "CONSUMER"
  }

Example JSON response body:

{"token" : { 
   "id" : "ab48a9efdfedb23ty3494",
    "expires" : "2010-11-01T03:32:15-05:00",
    "tenant" :{
      "id" : "t1000",
      "name" : "Consumer"
     }
   }, 
   "secondaryToken" : "1b07ae0018e34864b424a7ae0dd8e34",
   "refreshToken" : "C/poRbpxftaqZZ12JJYrWd2a1huDwEZ",
   "user" : { 
     "id" : "u123",
     "name" : "consumer",
     "roles" : [ { 
       "id" : "100",
        "name" : "ROLE_USER"      }, {
        "id": "101",
        "name": "object-store:admin",
        "tenantId": "t1000"
      } ] 
     } 
  }
  

For more information on use cases and examples, see Sample use cases.

Legacy CSA 3.x API authorization

With the exception of login and orgInformation, legacy API calls require a userIdentifier parameter, as well as a basic authorization header created using an integration account as described in Authentication with an integration account. Use the login API call to obtain a user's ID for the userIdentifier parameter. The user must have the necessary permissions to access the data requested by the API calls you will be making.

To get, for example, the user ID for user consumer in organization CONSUMER, submit the following URL (via an HTTP client or application code as will be described shortly):

https://<host>:<port>/csa/rest/login/CONSUMER/consumer

The <id> value in the following return body is the UserIdentifier value you would use in further Legacy API calls:

 <id>BFA0DB53DA414B90E04059106D1A24B5</id>
  <isCriticalSystemObject>false</isCriticalSystemObject>
  <description>service consumer user</description>
  <detailedDescription>service consumer user</detailedDescription>
  <iconUrl>http://localhost/csaconsumer/consumer</iconUrl>
  <name>consumer</name>
  <displayName>consumer</displayName>
  <state>
    ...
  </state>
  ...

This ID can be used in subsequent legacy API calls using https://<host>:<port>/csa/rest/<api call>?userIdentifier=<id>.