API Sub Account Management

Search Cloud One – Basic

API for Sub Account Management 1.0

The Sub Account Management endpoint (/SubAccountMgmt) is the endpoint where the master account holder can view and manage sub-users of their account.

The Endpoint accepts requests of contentType application/json only.

All requests must pass a valid APIKey. A Valid API Key is one that is either a ‘Master Account’ API Key, or an ‘API User’ Key where the given key has ‘Manage Users’ Permission. Organization MemberKeys are not valid.

Actions

All requests must pass a valid Action. There are three possible actions that can be passed:-

• ListAccounts Retrieve a list of accounts belonging to the master account holder.
• GetSubPerms Retrieve the permissions assigned to a sub account.
• CreateAccount Create an API User or Organization Member account.

ListAccounts

Requires no extra JSON parameters. Responds with a list of sub accounts tied to the master account, with their UserID, UserUUID, UserName, DisplayName and UserType.

See: UserTypes (TODO)

In the case that UserType is APIUser, DisplayName and UserName are the same.

Example Request

{
  "APIKey": "7e41ef06-6c0e-477e-b7e4-3103fc41fef2",
  "Action": "ListAccounts"
}

Example Response

{
  "SubAccounts": [
    {
      "UserID": "251",
      "UserUUID": "b611e40a-914e-45ce-b83e-6e752722ab71",
      "UserName": "john_smith27",
      "DisplayName": "John Smith",
      "UserType": "OrgMember"
    },
    {
      "UserID": "346",
      "UserUUID": "0df0c143-6c24-4c14-8b1b-7d6dcbffe8c7",
      "UserName": "Android App",
      "DisplayName": "Android App",
      "UserType": "APIUser"
    }
  ]
}

GetSubPerms

Requires UserID and UserUUID to be passed. Brings back whether or not the user is a master account, if it can along with an array of IndexPermissions.

Example Request

{
  "APIKey": "7e41ef06-6c0e-477e-b7e4-3103fc41fef2",
  "Action": "GetSubPerms",
  "UserID": "56462",
  "UserUUID": "19adb403-5c87-4ab9-8df1-12965069acd9"
}

Example Response

{
  "IsMaster": false,
  "IndexPermissions": [
    {
      "IndexID": "3512",
      "IndexUUID": "d2d9cbb5-63f1-4b87-b377-424d95fef0b9",
      "Read": true,
      "Write": true,
      "Delete": false,
      "AlterProperties": false
    },
    {
      "IndexID": "4657",
      "IndexUUID": "e53910af-92da-4986-bb5b-f178c08066aa",
      "Read": true,
      "Write": false,
      "Delete": false,
      "AlterProperties": false
    }
  ]
}

CreateAccount

Requires an AccountType and Username to be passed.

AccountType can be one of two types:

• OrgMember – For members of an organization who would login through the SearchCloudOne Management Console.
  • If passed, the request must also pass an Email and DisplayName.
  • Username must be a username that is unique to SearchCloudOne.
  • SearchCloudOne will automatically send an invitation to the passed Email Address, inviting the new user to activate their account.
  • When the user activates their account, they will set their own password.
  • Organization Members do not have access to the Users or API page.
  • Organization Members are able to reset their password and change their email address at any time. Their chosen email address is (at time of writing) not disclosed even to the master account holder.
• APIUser – An account used by programs (For instance, a Search Page on a Website, or an application).
  • If passed, Username can be any name unique to your account with any format.
  • It is recommended to pass a descriptive name such as ‘Android Application’, ‘www.example.com Search Page’ to help with analytics tracking and billing.

Example Create APIUser Request

{
  "APIKey": "0cf08d1d-7da5-4fa8-8fa1-c5bbe12e0bbf",
  "Action": "CreateAccount",
  "Username": "Android App",
  "AccountType": "APIUser"
}

Example Create OrgMember Request

{
  "APIKey": "0cf08d1d-7da5-4fa8-8fa1-c5bbe12e0bbf",
  "Action": "CreateAccount",
  "Username": "john_smith27",
  "DisplayName": "John Smith",
  "AccountType": "OrgMember",
  "Email": "john.smith@example.com"
}

Responses

No Response Body will be sent. Check the Response Status Code for success:

• 200 OK The account was created successfully.
• 409 Conflict The passed Username is already taken. Try another.
• 412 Precondition Failed Required fields are missing from the request
• 401 Unauthorized Passed an Invalid API Key (Expired or does not have permission to create a sub account)
• 400 Bad Request The passed AccountType was not recognized. (Case Sensitive)