What can we help you with?

e.g. Getting Started, Build Dashboards

Top

User Management

Follow

List Users:

This endpoint returns a listing the information of all the users in the workspace
GET /api/1.0/users

No parameters

Response

HTTP Status Response
200 OK Output example: 
{
   "list":[
      {
         "id":10077,
         "username":"someEmail1@someHost.com",
         "name":"Test8",
         "customerId":1033,
         "autocycle":false,
         "tempUser":false,
         "ssoUser":false,
         "newUser":false,
         "timeZone":"America/Los_Angeles",
         "userGroups":[
            {
               "id":889,
               "groupName":"Default"
            },
            {
               "id":890,
               "groupName":"group1"
            },
            {
               "id":891,
               "groupName":"group2"
            }
         ],
         "roles":[
            "admin"
         ],
         "free":false,
         "twoFactorAuth":false
      },
      {
         "id":10081,
         "username":"someEmail2@someHost.com",
         "customerId":1033,
         "autocycle":false,
         "tempUser":false,
         "ssoUser":false,
         "newUser":false,
         "timeZone":"America/Los_Angeles",
         "userGroups":[
            {
               "id":890,
               "groupName":"group1"
            }
         ],
         "roles":[
            "admin"
         ],
         "free":false,
         "twoFactorAuth":false
      }
   ]
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" https://www.knowi.com/api/1.0/users/

 

Get User

This endpoint returns all the information about a specific user of a given user Id
GET /api/1.0/users/<user_id>
Parameter Comments
user_id User id to get info about specified User

Response

HTTP Status Response
200 OK Output example: 
{
   "id":10091,
   "username":"someEmail1@someHost.com",
   "customerId":1033,
   "autocycle":false,
   "tempUser":false,
   "ssoUser":false,
   "newUser":false,
   "timeZone":"America/Los_Angeles",
   "userGroups":[
      {
         "id":889,
         "groupName":"Default"
      }
   ],
   "roles":[
      "viewer"
   ],
   "free":false,
   "twoFactorAuth":false
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to see specified user info

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"https://www.knowi.com/1.0/users/10001

 

Search User by Username

This endpoint returns a user detail of a given username
GET /api/1.0/users/search
Parameter Comments
userType the type of user to filter results (regular|sso|external)
username the username to search

Response

HTTP Status Response
200 OK Output example: 
{
   "id":10091,
   "username":"someEmail1@someHost.com",
   "customerId":1033,
   "autocycle":false,
   "tempUser":false,
   "ssoUser":false,
   "newUser":false,
   "timeZone":"America/Los_Angeles",
   "userGroups":[
      {
         "id":889,
         "groupName":"Default"
      }
   ],
   "roles":[
      "viewer"
   ],
   "free":false,
   "twoFactorAuth":false
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • The current user is not allowed to see the specified user info

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"https://www.knowi.com/api/1.0/users/search?username=email@acme.com&userType=sso

 

Create User

This endpoint is for creating a new user with specified information
POST /api/1.0/users/

POST JSON payload:

Parameter Comments
username User name of new user, actually the existing email of new user
password Password for new user
phone It is used to make and receive calls, send and receive text messages (SMS) linked to your account, and is also required in Two Factor Authentication (2FA) to log into Knowi.
userGroups userGroups is a nested object that contains objects here for backward compatibility the following properties are:

id: This is an id of the group
access_level: This is a level of the access
userRole This is the role of a user.
autoShareTo
Automatically share all assets created and linked to a user with the selected groups. This is useful within a team setting to collaborate on assets created by one user to be transferred to others automatically, without sharing individual assets explicitly.
Shared assets include any datasources, queries, widgets, and dashboards. Value is an array of JSON objects (groups) with an "id" field in each of groups to autoShareTo. For example, to auto-share to group with id 902: [{\"id\": 902 }]
contentFilters
It is an array of filters, used to filter content for users on dashboards and widgets that defines the field name, Type of field, value of that field, and Operator.
Optional (could be set to empty string), the content filters set to User. Example:
[{"fieldName":"$c9_<field>$", "type": "java.lang.String", "values":["33"], "operator": "Equals"}]

Available Operators for Content Filters:

"Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.
twoFactorAuth
User enters their username and password to log in, Once the credentials are verified, the system prompts the user for a second factor of authentication and gets verified Via SMS or Via Email.
Boolean value, if set to "true" then two-factor authorization (2FA) is enabled for the account
limitListingUsersToGroups
 
Limit sharing to groups. When set, this user will only see other users within the same groups to be able to share assets to.

Response

HTTP Status Response
200 OK Return created user json info (same as "Get user" command). Output example: 
{
   "id":10091,
   "username":"someEmail1@someHost.com",
   "customerId":1033,
   "autocycle":false,
   "tempUser":false,
   "ssoUser":false,
   "newUser":false,
   "timeZone":"America/Los_Angeles",
   "userGroups":[
      {
         "id":889,
         "groupName":"Default"
      }
   ],
   "roles":[
      "viewer"
   ],
   "free":false,
   "twoFactorAuth":false
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Invalid userInviteJson specified
  • Specified group is not exists
  • Invalid group specified
  • Invalid user role specified
  • Common error creating user via management api - details in the log at server
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
409 CONFLICT 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • User with such name already exists
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.

Example

 curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d "{\"username\":\"someEmail1@someHost.com\", \"password\":\"somePassword\", \"phone\":\"somePhone\", \"userGroups\":[{\"id\":889,\"access_level\":1}],\"userRole\":\"viewer\", \"autoShareTo\":[{\"id\":889,\"access_level\":1}], \contentFilters\=[{\"fieldName\":"Customer","\values\":["Facebook"],"\operator\":"="}]\", \"twoFactorAuth\":\"true/false\"}" http://localhost:9090/api/1.0/users

 

Delete User

This endpoint is for deleting a specific user of a given user id

Query

DELETE /api/1.0/users/<user_id>

Parameter Comments
user_id User id of User to delete

Response

HTTP Status Response
200 OK No response body
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Invalid json properties
  • Missed 'username' field in json
  • Missed 'password' field in json
  • Missed 'userInviteJson' field in json
  • Missed 'phone' field in json
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to delete specified user or user is not found

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE https://www.knowi.com/api/1.0/users/10084

 

Transfer User Assets to Another User

This endpoint is for moving the user assets to another user of a given user id

PUT /api/1.0/users/<userId>/moveAssets?toUserId=123456

Parameter Comments
userId User id of source user to transfer assets from
toUserId User id of destination user to transfer assets to
HTTP Status Response
200 OK No response body
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Invalid json properties
  • Missed 'username' field in json
  • Missed 'password' field in json
  • Missed 'userInviteJson' field in json
  • Missed 'phone' field in json
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to delete specified user or user is not found
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X PUT http://localhost:9090/api/1.0/users/10084/moveAssets?toUserId=10085

 

Edit User

This endpoint is for updating/modifying the user details of a given user id

Query

PUT /api/1.0/users/<user_id>

Parameter Comments
user_id User id of the user to edit

PUT JSON payload.
Any of fields are optional here (e.g. you can edit only required fields of user).

Parameter Comments
name Name of user (this is not username)
groups List of groups to which User is belongs, including access level (1 - Edit rights, 2 - read-only) Example of object: [{"name":"Default","id":889,"type":"Groups","access_level":1}]
roles The role of the account could be: admin, user, viewer
contentFilters

It is an array of filters, used to filter content for users on dashboards and widgets that defines the field name, Type of field, value of that field, and Operator.
Optional (could be set to empty string), the content filters set to User. Example:

[{"fieldName":"$c9_<field>$", "type": "java.lang.String", "values":["33"], "operator": "Equals"}]

Available Operators for Content Filters:

"Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.
timezone String timezone of the user location, e.g.: America/Los_Angeles. Click here for a list of valid timezones
twoFactorAuth (BOOL value) User enters their username and password to log in, Once the credentials are verified, the system prompts the user for a second factor of authentication and gets verified Via SMS or Via Email.
Boolean value, if set to "true" then two-factor authorization (2FA) is enabled for the account
phone It is used to make and receive calls, send and receive text messages (SMS) linked to your account, and is also required in Two Factor Authentication (2FA) to log into Knowi.
defaultDashboardId ID of the dashboard to be shown whenever user login
 autoShareTo Automatically share all assets created and linked to a user with the selected groups. This is useful within a team setting to collaborate on assets created by one user to be transferred to others automatically, without sharing individual assets explicitly.
Shared assets include any datasources, queries, widgets, and dashboards. Value is an array of JSON objects (groups) with an "id" field in each of groups to autoShareTo. For example, to auto-share to group with id 902: [{\"id\": 902 }]
limitListingUsersToGroups Limit sharing to groups. When set, this user will only see other users within the same groups to be able to share assets to.

Response

HTTP Status Response
200 OK Return created user json info (same as "Get user" command). Output example: 
{
   "id":10091,
   "username":"someEmail1@someHost.com",
   "customerId":1033,
   "autocycle":false,
   "tempUser":false,
   "ssoUser":false,
   "newUser":false,
   "timeZone":"America/Los_Angeles",
   "userGroups":[
      {
         "id":889,
         "groupName":"Default"
      }
   ],
   "roles":[
      "viewer"
   ],
   "free":false,
   "twoFactorAuth":false
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Common error saving user - details in the server log
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to edit specified user
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"name\":\"someName123\"}"https://www.knowi.com/api/1.0/users/10096
Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles