Managing Users

Overview

In this section, we will explore user management using the various User Roles outlined in the introduction and touched on in the Managing Partners section. This involves handling users within the context of their assigned roles, including Partners, Sub-Partners, and Clients. The specific User Roles and permissions required are dictated by another higher user creating it and the partner associated with that user. Understanding these roles and permissions is crucial for effective management and operation within the system. These users are used to configure API Authentication headers, control API permissions, manage actions in the ShieldConex Interface via the UI Portal, and maintain a secure organizational structure.

Sub-Partners are able to create users on the Sub-Partner Level and lower, whereas Partners with a direct relationship with Bluefin are able to create users on the System Level.

Depending on the user role (Partner Level and Client Level), the users can be created under Partners or Clients. As we have shown by the Hierarchy Diagram, Client Level users cannot view partners.

For the detailed overview and the hierarchy diagram, please refer to the Introduction.

Creating a User

Request

POST /api/v1/users

{
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Basic Base64(username:password)"
  },
  "body": {
    "userName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+14155552671",
    "partner": {
      "id": 904,
      "name": "partnerName"
    },
    "userRole": {
      "name": "Partner Supervisor"
    },
    "isActive": false,
    "sendWelcomeEmail": false
  }
}

Request Parameters

Parameter	Type	Description
`userName`	`string`	Must be unique
`phone`	`string`	The User's phone number without dashes, spaces, or brackets (e.g. +14155552671).
`partner`	`object`	Reference to the associated Partner - `id` and `name`. This field is required when the user is under the Partner Level User Role.
`client`	`object`	The users can also be created for either a Partner, or a Client. To create a user under a Client, the client reference must be included. This field is required when the user is under the Client Level User Role. See Getting Users.
`userRole`	`object`	The user role assigns the name field containing the user role. Enum: [ `System Administrator`, `System User`, `Partner Supervisor`, `Partner User`, `Client Administrator`, `Client User` ]
`isActive`	`boolean`	This property indicates if the Client account is active or disabled. It is not possible to delete Clients, however their account can be set to inactive.
`sendWelcomeEmail`	`boolean`	If set to `true`, the user will be sent a welcome email.

For all the parameters, refer to the comprehensive API Reference.

Response

{
  "id": 2984
}

Getting Users

This request returns a summarized list of all Users assigned to a partner. As opposed to Getting Partners, the list doesn't include all the users of the sub-partners and vice versa.

A partner can also lookup a Client's Users by including the client id or name as a query parameter.

Request

GET /api/v1/users?partner=partnerName

{
  "method": "GET",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Basic Base64(username:password)"
  }
}

Query Parameters

Parameter	Type	Required	Description
`partner`	`string/integer`	Yes	Filter the list by Partner. The parameter value can be either a Partner ID or Name.
`client`	`string/integer`	No	Filter the list by Client. The parameter value can be either the Client's ID or Name. To view the filtered users when using this parameter, the users have to have the Client Level User Role. Typically, we just apply the `partner` unless we specifically need to get the users with the Client Level User Role under that client.
`take`	`integer`	No ( Default: `10`)	The number of entries to include in the list. It starts from `skip`.
`skip`	`integer`	No ( Default: `0` )	The number of results to skip before listing entries.

Response

{
  "total": 3,
  "data": [
    {
      "id": 2984,
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+14155552671",
      "userName": "John Doe",
      "isActive": false,
      "version": 0,
      "partner": {
        "id": 904,
        "name": "myPartner"
      }
    },
    {
      "id": 2936,
      "firstName": "Alice",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "+14155552671",
      "userName": "Alice Smith",
      "isActive": false,
      "version": 0,
      "partner": {
        "id": 904,
        "name": "myPartner"
      }
    },
    {
      "id": 2952,
      "firstName": "Josh",
      "lastName": "Jones",
      "email": "[email protected]",
      "phone": "+14155552671",
      "userName": "Josh Jones",
      "isActive": false,
      "version": 0,
      "partner": {
        "id": 904,
        "name": "myPartner"
      }
    }
  ]
}

NOTE: As it can be seen from the output, all the users originate from the same partner, "myPartner".

Getting Client Level Users

Here, we show that clients can have (Client Level) users on their own by specifying the client id in the URL query.

GET /api/v1/users?client=744

{
  "method": "GET",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Basic Base64(username:password)"
  }
}

Response

{
  "total": 2,
  "data": [
    {
      "id": 3080,
      "firstName": "Joe",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "+14155552671",
      "userName": "Joe Smith",
      "isActive": false,
      "version": 0,
      "client": {
        "id": 744,
        "name": "Test Client"
      }
    },
    {
      "id": 3096,
      "firstName": "James",
      "lastName": "King",
      "email": "[email protected]",
      "phone": "+14155552671",
      "userName": "James King",
      "isActive": false,
      "version": 0,
      "client": {
        "id": 744,
        "name": "Test Client"
      }
    }
  ]
}

Getting a User

To get a more detailed user meta-data such as created, modified, and userRole, the id of the user needs to be specified in the URL path.

Request

GET /api/v1/clients/{id}

{
  "method": "GET",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Basic Base64(username:password)"
  }
}

Response

{
  "id": 2936,
  "firstName": "Alice",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+14155552671",
  "userName": "Alice Smith",
  "isActive": false,
  "created": "2024-08-14T00:04:56.000Z",
  "modified": "2024-08-14T15:35:10.000Z",
  "version": 0,
  "partner": {
    "id": 904,
    "name": "myPartner"
  },
  "userRole": {
    "id": 3,
    "name": "Partner User"
  }
}

Client Level Users

In the case of the Client Level role, instead of returning the partner - it will provide the client field as Client Level users cannot look into their clients' partners.

For example,

{
  "id": 3080,
  "firstName": "Joe",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+14155552671",
  "userName": "Joe Smith",
  "isActive": false,
  "created": "2024-08-15T15:57:14.000Z",
  "modified": "2024-08-15T15:57:14.000Z",
  "version": 0,
  "client": {
    "id": 744,
    "name": "Test Client"
  },
  "userRole": {
    "id": 5,
    "name": "Client User"
  }
}

Updating a User

Updating a user involves changing any of the parameters from userName to userRole set by Creating a User.

Request

PATCH /api/v1/users/{id}

{
  "method": "PATCH",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Basic Base64(username:password)"
  },
  "body": {
    "userName": "John Doe Changed",
    "partner": {
      "id": 920,
      "name": "otherSubPartner"
    },
    "userRole": {
      "name": "Partner User"
    },
    "isActive": false,
    "sendWelcomeEmail": false
  }
}

Response

200

{
  "id": 2984
}

403

{
  "uuid": "c1b5b7d0-5a50-11ef-9fca-7d5196e53ec9",
  "errorCode": 7403,
  "message": "Permission denied."
}