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.