Create a new user

Use the Create New User API to create a new user in the Control Room.

Prerequisites

View and Manage Users

Authenticate with a user that has the following ADMINISTRATION permissions:

  • View users

    Users with these permissions are able to create and manage users. These are administrator permissions. It is recommended that non-administrator users be given limited permissions for creating and managing users. Learn how to create a role with limited permissions that can be assigned to users.

    • Create users
    • Edit users
    • Delete users
  • View licenses

    Users with these permissions are able to view and manage device licenses. Device licenses are required to enable users to perform specific tasks. For example, Bot Creators require a DEVELOPMENT device license in order to create bots.

    Manage user's device license

JSON Web Token (JWT)
All Control Room APIs require a JSON Web Token (JWT) to access the APIs. Generate an authentication token using the Authentication API. See Enterprise 11 Authentication API.
Minimum required parameters
  • Roles: Each user must have at least one role. The role id is required to create a role from the User Management API.

    Role based accessibility enables appropriate access to relevant data and actions.

    Note: For this example, we created a Bot Creator user. In the request body we assigned the following Enterprise 11: System created roles:
    • AAE_Basic (ID: 2)
    • AAE_Meta Bot Designer (ID: 13)
  • username: String (255 max)
  • email: Must conform to standard email format (username@domain.com)
  • password: String: 8-15 characters in length. Allowable characters: a-z, A-Z, 0-9, @, -, _, !, #, $, %, &, and . (period)
Additional recommended parameters
  • "enableAutoLogin": true
  • "username": "NumerOneUser"
  • "firstName": "Doc"
  • "lastName": "Writer"
  • "email": "username@mydomain.com"
  • "password": "changeme"
  • "description": "Test user creation."
  • "licenseFeatures": [ DEVELOPMENT, RUNTIME, IQBOTRUNTIME, ANALYTICSCLIENT, ANALYTICSAPI ]

    Users can be created without an assigned device license. There are System default licenses that enable privileges for specific users and roles.

  • Use the Swagger installed with your Control Room to test the APIs. View the available APIs at: http://<your_control_room_url>/swagger/
  • You can also use a REST client to complete this task.

Procedure

  1. Add an authentication token to the request header.
    Use the Authentication API to generate a JSON Web Token. See Enterprise 11 Authentication API.
  2. Select POST as the method.
    POST http://<your_control_room_url>/v1/usermanagement/users
  3. In the request body, enter the mandatory parameters and recommend parameters.

    Request body :

    {
      "roles": [
        {
          "id": 2
        },
        {
          "id": 13
        }
      ],
      "enableAutoLogin": true,
      "username": "BotCreatorUser",
      "firstName": "Robert",
      "lastName": "Developer",
      "email": "bob.dev@mydomain.com",
      "password": "changeme",
      "description": "Go create great bots.",
      "licenseFeatures": [
        "DEVELOPMENT"
      ]
    }
  4. Send the request.
    • In Swagger, click Execute.
    • In a REST client, click SEND.

    The response returns user details.

    Response body:
    {
      "id": 61,
      "email": "bob.dev@mydomain.com",
      "username": "botcreatoruser",
      "domain": null,
      "firstName": "Robert",
      "lastName": "Developer",
      "version": 0,
      "principalId": 61,
      "deleted": false,
      "roles": [
        {
          "name": "AAE_Basic",
          "id": 2,
          "version": 0
        },
        {
          "name": "AAE_Meta Bot Designer",
          "id": 13,
          "version": 0
        }
      ],
      "sysAssignedRoles": [],
      "groupNames": [],
      "permissions": [
        {
          "id": 97,
          "action": "viewbotstore",
          "resourceId": null,
          "resourceType": "botstore"
        },
        {
          "id": 33,
          "action": "upload",
          "resourceId": "7",
          "resourceType": "repositorymanager"
        },
        {
          "id": 61,
          "action": "createstandard",
          "resourceId": null,
          "resourceType": "credentialattribute"
        },
        {
          "id": 93,
          "action": "download",
          "resourceId": "9",
          "resourceType": "repositorymanager"
        },
        {
          "id": 134,
          "action": "viewuserbasic",
          "resourceId": null,
          "resourceType": "usermanagement"
        },
        {
          "id": 29,
          "action": "view",
          "resourceId": null,
          "resourceType": "repositorymanager"
        },
        {
          "id": 62,
          "action": "metabotdesigner",
          "resourceId": null,
          "resourceType": "metabot"
        },
        {
          "id": 34,
          "action": "download",
          "resourceId": "7",
          "resourceType": "repositorymanager"
        },
        {
          "id": 92,
          "action": "upload",
          "resourceId": "9",
          "resourceType": "repositorymanager"
        }
      ],
      "licenseFeatures": [
        "DEVELOPMENT"
      ],
      "emailVerified": true,
      "passwordSet": false,
      "questionsSet": false,
      "enableAutoLogin": true,
      "disabled": false,
      "clientRegistered": false,
      "description": "Go create great bots.",
      "createdBy": 19,
      "createdOn": "2020-02-09T23:25:20Z",
      "updatedBy": 19,
      "updatedOn": "2020-02-09T23:25:20Z",
      "publicKey": null,
      "appType": null,
      "routingName": null,
      "appUrl": null
    }
Note: You can also run REST requests from a command terminal. The following is a curl request example. This example is formatted for readability. Replace the text inside the angle brackets, <authentication_token>, with your authentication token.
curl -X POST -H 'X-Authorization: <authentication_token>' -i '<your_control_room_url>/v1/usermanagement/users' --data '{
  "roles": [
    {
      "id": 2
    },
    {
      "id": 13
    }
  ],
  "enableAutoLogin": true,
  "username": "BotCreatorUser",
  "firstName": "Robert",
  "lastName": "Developer",
  "email": "bob.dev@mydomain.com",
  "password": "changeme",
  "description": "Go create great bots.",
  "licenseFeatures": [
   "DEVELOPMENT"
  ]
}'

Next steps

  • You can verify that the user was created by logging in to the Control Room as the user that you created.
  • System assigned roles, sysAssignedRoles, include a set of permissions that are required by the roles you assigned to the user and default roles that are assigned to all users.