What can we help you with?

e.g. Getting Started, Build Dashboards

Top

User Management

Follow

List Users: 

Query

GET /api/1.0/users

Get information about all users in the workspace

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

Query

GET /api/1.0/users/<user_id>

Get information about user by 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

Query

GET /api/1.0/users/search

Returns a user detail by username

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

Query

POST /api/1.0/users/

Create a user with specified information

POST JSON payload:

Parameter Comments
username User name of new user, actually the existing email of new user
password Password for new user
phone Phone number for new user (required if using 2FA)
userInviteJson JSON of "invite" properties which include: user role (possible values: user, viewer, admin), user groups to which user will belong, which include group id, access level (possible values: 1, 2, where 1 - Edit rights, 2 - Read-only rights). Example: 
{
  "userGroups":
    [
      {
        "id":889,
        "access_level":1
      }
    ],
  "userRole":"viewer"
}

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\", \"userInviteJson\": {\"userGroups\":[{\"id\":889,\"access_level\":1}],\"userRole\":\"viewer\"} }"https://www.knowi.com/api/1.0/users

 

Delete User

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

Query

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

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 PUT http://localhost:9090/api/1.0/users/10084/moveAssets?toUserId=10085

Edit User

Query

PUT /api/1.0/users/<user_id>

Parameter Comments
user_id User id of the user to delete

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 Role of the account, could be: admin, user, viewer
contentFilters 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"}]
timezone String timezone of the user location, e.g.: America/Los_Angeles. Click here for a list of valid timezones
twoFactorAuth (BOOL value) Boolean value, if set to "true" then 2FA (two factor) authorization is enabled for the account
phone Phone number of the account. Mostly useful together with "twoFactorAuth" variable
defaultDashboardId ID of the dashboard to be shown whenever user login
 autoShareTo Automatically share all assets created by user to the selected groups. This is useful within a team setting to collaborate on assets created by one user to be shared to others automatically, without sharing indivudal assets explicity. Shared assets includes any datasources, queries, widgets and dashboards. Value is array of json objects (groups) with "id" field in each of group to autoshare-to. Example, to auto-share to group with id 902: [{\"id\": 902 }]

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