Manage accounts with /config/users

Use /config/users to retrieve, create, and configure V‑Spark user accounts, to retrieve user account status, to retrieve the authorization method used for login, and to retrieve or configure the permissions that they have in V‑Spark and within each company.

Note: There are 3 user attributes the /config/users cannot update:

approved — Account approval status cannot be set to 1.
auth.method — Authentication method, which can only be specified when creating a user.
password

/config POST requests must include entity information as top-level JSON data. Higher-level entity information does not need to be included in JSON POST data when entity names are included as path parameters.

Data written to V‑Spark with /config is additive—that is, if objects in request JSON data exist, they are configured to use the request JSON. Objects that do not exist are created.

Set user permissions

Use /config/users/ to set View (read) and Create/Edit (write) permissions for a user. Account permissions may be set for the system, a company, or an organization, depending on the request token's permissions scope.

Important: When viewing or modifying user permissions via the API but verifying them in the GUI, you must be logged in to the GUI as a user who is authorized to see any changes that have been made. User accounts see only changes that have been made at a level that is equal to or lower than the authorization level of the account that made the change.

System permissions

System administrator access gives the user account read and write permissions to every aspect of the V‑Spark host system. That means they can create, delete, and modify any company, organization, folder, application, or user account on the system.

Sysadmins can also approve user accounts, change user account passwords, create and delete system-wide announcements, and enable system-wide readonly mode.

The following example JSON describes a user account with sysadmin access.

"DocTestCo": {
    "test.user.01": {
        "name": "System Administrator",
        "email": "test.user.01@company.com",
        "company": "DocTestCo",
        "auth": {
            "verified": false,
            "disabled": false,
            "method": "standard"
            },
        "permissions": {
            "system": [
                "write"
            ]
        }
    }...
}...

Company permissions

Company-level access gives the user account read and write permissions for individual companies.

Company View (read) permission enables the user to view dashboards and transcripts for any organization under that company.

Company Create/Edit (write) permission enables the user to

create and add user accounts to that company.
modify permissions for company user accounts.
create and edit company organizations, folders, and applications.

The following example JSON describes a user account with read and write access to the company DocTestCo.

"manual.user.03": {
    "auth": {
        "disabled": false,
        "verified": true,
        "method": "standard"
        },
    "company": "DocTestCo",
    "email": "manual.user.03@company.com",
    "name": "Manual User 03",
    "permissions": {
        "DocTestCo": {
            "all": [
                "read",
                "write"
            ]
        }
    }...
}...

Organization permissions

Organization-level access gives the user account read and write permissions for individual organizations.

Organization View (read) permission enables the user to view organization dashboards and transcripts.

Organization Create/Edit (write) permission enables the user to create and modify organization folders and applications.

The following example JSON describes a user account with read and write access to the organization DocTesting, which is under the company DocTestCo.

"manual.user.03": {
   "auth": {
      "disabled": false,
      "verified": true,
      "method": "standard"
   },
   "company": "DocTestCo",
   "email": "manual.user.03@company.com",
   "name": "Manual User 03",
   "permissions": {
      "DocTestCo": {
         "orgs": {
            "DocTestCo-DocTesting": [
               "read",
               "write"
            ]...
         }
      }...
   }...
}...

GET and POST JSON differences

The /config/usersAPI supports additional name/value pairs that can be used as part of your JSON input when programmatically creating user accounts. These fields are in addition to those in sample JSON output.

Table 1. /config/users/ Fields
Name		Type	Values	Description
`password`				Enables you to specify the password that will be assigned to a user account when it is created. An example of specifying a password using this field is the following: `"password": "changeme",` If the `password`field is not included in the `auth`section of the JSON for a user, a reset password link will be emailed to the new user. The sample JSON below is for a user who has system administration permissions for their home company ( `DocTestCo`, in this case) and has a default password of `changeme`. Figure 1. Sample User JSON Including a Password Field `{ "test.user.02": { "name": "Company-Level Administrator", "email": "test.user.02@example.com", "company": "DocTestCo", "auth": { "verified": true, "disabled": false, "method": "standard", "password": "changeme" }, "permissions": { "DocTestCo": { "all": [ "read", "write" ] } } } },...`
`method`			standard, oidc	Specify the user's login authorization method. `standard` specifies internal V‑Spark authorization. `oidc` specifies OpenID Connect for single sign-on implementations. Once a user's authorization method has been set, it cannot be changed.

Important: When creating a user account that will be integrated with an external authorization mechanism, the Username for the account that you are creating must be the same in V‑Spark as it is in the external authorization mechanism. This username may be a simple username, an email address, or a "user principle name" (UPN), depending on the service.

Optional /config/users/ fields can also be used in JSON sent to /config/CO-SHORT/users/. The main difference between those two endpoints is that /config/users/ JSON must include the primary company for each user.