Create a Customer

This page describes how to programmatically create, manage, and log in to customer tenants using the CyberArk Identity API.

Before continuing, ensure you are familiar with:

The remainder of this document assumes that you have already authenticated the user and have obtained the authentication token necessary to invoke subsequent endpoints.

Step 1. Get a List of Pod Regions

In order to create a tenant, you need to specify a Pod region. You can get a list of regions using the /msp/getavailablepodregions endpoint:

POST https://mytenant.idaptive.app/msp/getavailablepodregions

The Result field in the response contains the list of available regions:

{  
   "success":true,
   "Result":[  
      "Asia-Pacific",
      "US West",
      "South America",
      "Hong-Kong",
      "Canada",
      "Europe",
      "US East",
      "Australia",
      "Japan"
   ],
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Step 2. Determine Alias Availability

In addition to the region, you will also need to specify an alias (domain name) when creating the tenant. But before you can use an alias you must first determine if that alias is available for use by invoking the /msp/getaliasavailability endpoint.

Invoke the /msp/getaliasavailability endpoint and pass in the desired alias via the alias parameter:

POST https://mytenant.idaptive.app/msp/getaliasavailability

{  
   "alias":"myidaptive.app"
}

The StatusCode field in the response indicates if the alias is available or already in use on the tenant, and the Tenant field indicates the ID of the tenant that the StatusCode applies to:

{  
   "success":true,
   "Result":{  
      "StatusCode":"AliasInUse",
      "Tenant":"AAX1234"
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

If the response indicates that the alias is not available for use (i.e. it's already in use), then you will need to choose a different alias (e.g. use the same alias with a slight variation in spelling), and check the availability of that alias using the /msp/getaliasavailability endpoint.

Step 3. Creating the Tenant

Create the tenant using the /msp/createnewsmb endpoint and passing in the customer information in the body of the request. Pass the region for the pod via the podRegion parameter and the available alias that you want to use via the initialAlias parameter:

POST https://mytenant.idaptive.app/msp/createnewsmb

{  
   "company":"JohnTest",
   "customerName":"[email protected]",
   "podRegion":"Asia-Pacific",
   "adminUser":"mspadmin",
   "initialAlias":"idaptive.app",
   "customerData":{  
      "Country":"United States",
      "State":"CO",
      "Company":"JohnTest"
   }
}

The success field in the response indicates if the request was successful and the Result field contains information about the newly created tenant:

{  
   "success":true,
   "Result":{  
      "TenantId":"AAX1234",
      "AdminUser":"mspadmin",
      "AdminPass":"password1234",
      "PodFqdn":"AAX1234.mytenant.idaptive.app",
      "PodName":"APAC-AB-1",
      "AuthCookie":"589...",
      "ProxyCode":"AAX0...",
      "AdminUuid":"c2c7b..."
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Add Suffix

Add a suffix using the /core/StoreAlias endpoint and passing in the suffix information in the body of the request.

POST https://mytenant.idaptive.app/core/StoreAlias

{
  "alias":"loginsuffix",
  "domain":"mappedsuffix",
  "cdsAlias":"true",
  "oldName":""
}

Modify Suffix

Modify a suffix using the /core/StoreAlias endpoint and passing in the suffix information in the body of the request. Ensure the JSON includes oldName if there is change in the login suffix.

POST https://mytenant.idaptive.app/core/StoreAlias

{
  "alias":"loginsuffix1",
  "domain":"mappedsuffix",
  "cdsAlias":"true",
  "oldName":"loginsuffix"
}

Logging in to the Tenant

In order to programmatically log in to a customer tenant, you must first obtain a management link to the tenant. You can then use the OneTimePass value contained in that link to perform the log in.

Getting the Management Link

Get the management link using the /msp/getmanagementlink endpoint passing in the ID of the newly created tenant or the ID of an existing tenant via the tenantID body parameter:

POST https://mytenant.idaptive.app/msp/getmanagementlink

{  
   "tenantId":"AAX1234"
}

The Result field in the response contains the management link:

{  
   "success":true,
   "Result":"https://Pod1234.idaptive.app/manage?OneTimePass=L3dVSFFVRll...",
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Logging in Using the Management Link

Extract the OneTimePass query parameter from the response above and log in by invoking the /manage endpoint and including the OneTimePass parameter in the URL:

GET https://aax1234.my.idaptive.app/manage?OneTimePass=L3dVSFFVRl...&msp=true

The response contains the HTML to render the tenant that you just logged in to:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Content-Type: text/html; charset=utf-8
Expires: -1
Vary: Accept-Encoding
X-CFY-TX-PN: APAC-SE-1
X-CFY-TX-ID: 8fcbbcd950524afc984fd64d945a702d
X-CFY-TX-DT: NS8xNy8yMDE4IDU6MjM6MTAgUE0_
X-Frame-Options: SAMEORIGIN
P3P: CP="NON COR ADMa CURa DEVa OUR IND COM UNI NAV INT PRE LOC ONL PHY STA ONL"
X-UA-Compatible: IE=8,9,10
Strict-Transport-Security: max-age="31536000"
X-CFY-TX-TM: 1986
Set-Cookie: 
...

<!DOCTYPE html>
<html>
<head>
   <script type="text/javascript">
        window.DOCUMENT_FIRST_RECIEVED_TIME = new Date().getTime();
    </script>
    <title>Admin Portal</title>
    <meta http-equiv="X-UA-Compatible" content="IE=8,9,10" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <link rel="shortcut icon" href="/vfslow/lib/ui/../uibuild/compiled/idaptive/production/resources/images/logos/idaptive-16-1.png"/>

    <link href='/vfslow/lib/ui/../uibuild/compiled/idaptive/production/resources/fonts/Roboto.css?_ver=1526341884' rel='stylesheet' type='text/css'>
    <link href='/vfslow/lib/ui/../uibuild/compiled/idaptive/production/resources/fonts/Redacted.css?_ver=1526341884' rel='stylesheet' type='text/css'>
    <link href='/vfslow/lib/ui/../uibuild/compiled/idaptive/production/resources/fonts/Icon-Set.css?_ver=1526341884' rel='stylesheet' type='text/css'>

Getting a List of Tenants

You can get a list of tenants by invoking the following query:

POST https://mytenant.idaptive.app/RedRock/query

{  
   "Script":"Select * from Tenant ORDER BY ID COLLATE NOCASE",
   "Args":{  
      "PageNumber":1,
      "PageSize":100,
      "Limit":100000,
      "SortBy":"",
      "direction":"False",
      "Caching":-1
   }
}

The Results field in the response contains a collection of objects each describing an existing customer tenant:

{  
   "success":true,
   "Result":{  
      "IsAggregate":false,
      "Count":6,
      "Columns":[  
         {  
            "Name":"Status",
            "IsHidden":false,
            "DDName":"Status",
            ...
         },
         ..
      ],
      "FullCount":6,
      "Results":[  
          {  
            "Entities":[  
               {  
                  "Type":"Tenant",
                  "Key":"AAX1234",
                  "IsForeignKey":false
               }
            ],
            "Row":{  
               "CompanyName":"JohnTest",
               "Status":true,
               "ID":"AAX1234",
               "PodFqdn":"AAX1234.mytenant.idaptive.app",
               "_MatchFilter":null
            }
         },
         ...
      ],
      "ReturnID":""
   },
   ...
}

Enabling or Disabling a Tenant

You can enable or disable a tenant by invoking the /msp/SetTenantState endpoint and passing the ID of a tenant in the tenantId body parameter and "Enabled" or "Disabled" in the state parameter:

POST https://mytenant.idaptive.app//msp/SetTenantState

{  
   "tenantId":"AAX1234",
   "state":"Disabled"
}

The success field in the response indicates if the customer tenant was successfully enabled or disabled:

{  
   "success":true,
   "Result":true,
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Try the API in Postman:
Run in PostmanRun in Postman