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

Note If you log in to the Cloud Service Management Console, a CSRF (Cross-Script-Request-Forgery) token called x-csrf-token is created. This is added to the cookie.
For example,
Cookie: JSESSIONID=DIxnGcNlHazpEAfSdKNvy-KA.csaqa-vm22; X-Auth-Token=eyJ0eXujSc; XSRF-TOKEN=1a11afb8-b057-4f03-8b52-4bad19e3553a; orgName=TEST.COM

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>

Note The token has an expiration time. Generate a new one on expiry error.

Note You must include the header information with all API calls.

The administrator credentials may be required for some API calls.

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.

Note: Error code 401 (Not authorized) will be returned if the same user is not specified for authorization and for authentication. The exception to this is when csaTransportUser is used for authentication as it is accepted for authorization on behalf of other users.

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>.