Purpose

Creates a user account.

URL

https://<myserver>:<port>/api/admin/users

Method

POST

URL Parameters

<myserver> is the hostname or IP address of the machine hosting the Hybrid Data Pipeline server for a non-load balancer deployment, or the machine hosting the load balancer for a load balancer deployment. For a non-load balancer deployment, <port> is the port number specified as the Server Access Port during deployment. For a load balancer deployment, <port> must be either 80 for http or 443 for https. Whenever port 80 or 443 are used, it is not necessary to include the port number in the URL.

Request Payload Properties

The request takes the following format. The properties of the request are described in the table that follows.

{
    "userName": "user_name",
    "tenantId": tenant_id,
    "statusInfo": {status_information},
    "passwordInfo": {password_information},
    "permissions": {permissions},
    "authenticationInfo": {authentication_information}
    }
Property Description Usage Valid Values
"userName" The name of the user account. Required The maximum length is 128 characters.
"tenantId" The ID of the tenant to which the user belongs. Optional A valid tenant ID.
Note: When tenantId is not specified, the user is created in the tenant in which the administrator executing the operation resides.
"statusInfo" The status of the user account defined by the status property and additional properties associated with an account lockout policy. Required See statusInfo Object for details.
"passwordInfo" Password information associated with the user account defined by the password, passwordStatus, and passwordExpiration properties. Optional See passwordInfo Object for details.
"permissions" Permissions associated with the user account in terms of the role(s) and permissions set explicitly on the account. User account permissions are the sum of the permissions on associated role(s) and permissions set explicitly on the account. A user account may only be assigned roles in their tenant. Optional See permissions Object for details.
"authenticationInfo" Authentication information associated with the user account as defined by the authUserName and authServiceId properties. The authenticationInfo object does not need to be included in a request payload when the default internal authentication service is being used. When an external authentication service is being used, authenticationInfo must be included in the request payload. If authenticationInfo is not passed, a default authenticationInfo object is created where the userName of the account object is used as the authUserName and the authServiceId specifies the ID of the internal authentication service (1). Optional See authenticationInfo Object for details.

Sample Payload Requests

Example 1 payload request The following example shows a payload request to create a user account that uses the internal authentication service. In this scenario, the end user would authenticate with the username associated with the user account (testuser).

{
    "userName": "testuser",
    "tenantId": 26,
    "statusInfo": {
        "status": 1,
        "accountLocked": false
    },
    "passwordInfo": {
        "password": "TempPassword",
        "passwordStatus": 1,
        "passwordExpiration": "2020-01-01 00:00:00"
    },
    "permissions": {
        "roles": [
            86
        ]
    }
}

Example 2 payload request The following example shows a payload request to create a user account using an external authentication service. Here the end user (user_external) authenticates via an external authentication service ("authServiceId": 2). This end user inherits all the attributes associated with the testuser account.

{
    "userName": "testuser",
    "statusInfo": {
        "status": 1,
        "accountLocked": false
    },
    "passwordInfo": {
        "passwordStatus": 1,
        "passwordExpiration": "2020-01-01 00:00:00"
    },
    "permissions": {
        "roles": [
            2
        ]
    },
    "authenticationInfo": {
        "authUsers": [
            {
                "authUserName": "user_external",
                "authServiceId": 2
            }
        ]
    }
}

Example 3 payload request The following payload request creates a user account that supports both the internal authentication service or an external authentication service. The end user testuser may authenticate through the internal authentication service. Alternatively, the end user user_external can, with a distinct set of credentials, authenticate via the external authentication service "authServiceId": 2.

{
    "userName": "testuser",
    "statusInfo": {
        "status": 1,
        "accountLocked": false
    },
    "passwordInfo": {
        "password": "TempPassword",
        "passwordStatus": 1,
        "passwordExpiration": "2020-01-01 00:00:00"
    },
    "permissions": {
        "roles": [
            2
        ]
    },
    "authenticationInfo": {
        "authUsers": [
            {
                "authUserName": "user_external",
                "authServiceId": 2
            },
            {
                "authUserName": "testuser",
                "authServiceId": 1
            }
        ]
    }
}

Sample Success Responses

Example 1 success response

   Status code: 201
   Successful response
{
    "id": 3,
    "userName": "testuser",
    "tenantId": 26,
    "statusInfo": {
        "status": 1,
        "accountLocked": false
    },
    "passwordInfo": {
        "password": "TempPassword",
        "passwordStatus": 1,
        "passwordExpiration": "2020-01-01 00:00:00"
    },
    "permissions": {
        "roles": [
            86
        ]
    },
    "authenticationInfo": {
        "authUsers": [
            {
                "authUserName": "testuser",
                "authServiceId": 1
            }
        ]
    }
}

Example 2 success response

   Status code: 201
   Successful response
{
    "id": 4,
    "userName": "testuser",
    "statusInfo": {
        "status": 1,
        "accountLocked": false
    },
    "passwordInfo": {
        "passwordStatus": 1,
        "passwordExpiration": "2020-01-01 00:00:00"
    },
    "permissions": {
        "roles": [
            2
        ]
    },
    "authenticationInfo": {
        "authUsers": [
            {
                "authUserName": "user_external",
                "authServiceId": 2
            }
        ]
    }
}

Example 3 success response

   Status code: 201
   Successful response
{
    "userName": "testuser",
    "statusInfo": {
        "status": 1,
        "accountLocked": false
    },
    "passwordInfo": {
        "password": "TempPassword",
        "passwordStatus": 1,
        "passwordExpiration": "2020-01-01 00:00:00"
    },
    "permissions": {
        "roles": [
            2
        ]
    },
    "authenticationInfo": {
        "authUsers": [
            {
                "authUserName": "user_external",
                "authServiceId": 2
            },
            {
                "authUserName": "testuser",
                "authServiceId": 1
            }
        ]
    }
}

Sample Server Failure Response 

{
   "error":{
      "code":222207415,
      "message":{
         "lang":"en-US",
         "value":"UserName 'Joe' already exists."
      }
   }
}

Authentication

Basic Authentication using Login ID and Password

Authorization

The user must have the Administrator (12) permission, or the CreateUsers (13) permission and administrative access on the tenant.

Note: Administrator users cannot grant permissions they do not have to other user accounts.