Security Requirements and Controls
API Stability Long-Term

The addUserV2() GraphQL mutation may be used to add or invite a new user. Using this with an invitation token will activate the account. By activating the account, the client accepts LogScale's Terms and Conditions.

For more information on user authorization, see the Manage Users and Permissions documentation page. To add users from the LogScale graphical user interface, see Create user accounts section.

Syntax

Below is the syntax for the addUserV2() mutation field. Input would be given within the parentheses. The resulting changes will occur within LogScale, but can be returned and captured by specifying the elements desired within the userOrPendingUser type.

graphql
addUserV2(
      input: AddUserInputV2!
   ): userOrPendingUser!

The AddUserInputV2 above would be replaced by parameters with their values, in a comma-separated list, all within a pair of curly brackets. See the examples below for a better understanding.

Raw
graphql
mutation {
  addUserV2 (
    input: {
      username: "steve"
      sendInvite: true
      email: "steve@company.com"
    }
  ) {__typename ... on User {id, username}}
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  addUserV2 (
    input: {
      username: \"steve\"
      sendInvite: true
      email: \"steve@company.com\"
    }
  ) {__typename ... on User {id, username}}
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  addUserV2 (
    input: {
      username: \"steve\"
      sendInvite: true
      email: \"steve@company.com\"
    }
  ) {__typename ... on User {id, username}}
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  addUserV2 ( ^
    input: { ^
      username: \"steve\" ^
      sendInvite: true ^
      email: \"steve@company.com\" ^
    } ^
  ) {__typename ... on User {id, username}} ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  addUserV2 (
    input: {
      username: \"steve\"
      sendInvite: true
      email: \"steve@company.com\"
    }
  ) {__typename ... on User {id, username}}
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  addUserV2 (
    input: {
      username: \"steve\"
      sendInvite: true
      email: \"steve@company.com\"
    }
  ) {__typename ... on User {id, username}}
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  addUserV2 (
    input: {
      username: \"steve\"
      sendInvite: true
      email: \"steve@company.com\"
    }
  ) {__typename ... on User {id, username}}
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  addUserV2 (
    input: {
      username: \"steve\"
      sendInvite: true
      email: \"steve@company.com\"
    }
  ) {__typename ... on User {id, username}}
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL/graphql',
  path: '/graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();
Example Responses
Success (HTTP Response Code 200 OK)
json
{
  "data": {
    "addUserV2": {
      "__typename": "User",
      "id": "mQ2oDkHSLhTG6l6ppsmxJYHJ",
      "username": "steve"
    }
  }
}

This is a simple example of how to add a new user to LogScale &mdash; and to have the system send that user an invitation by email. To capture and confirm some of the results, the User return type was added with a couple of parameters. You can see this in the results.

Given Datatypes

For AddUserInputV2, there are several parameters that may be given. Below is a list of them along with their data type and a description of each:

Table: AddUserInputV2

ParameterTypeRequiredDefaultStabilityDescription
Some arguments may be required, as indicated in the Required column. For some fields, this column indicates that a result will always be returned for this column.
Table last updated: Sep 17, 2024
companystring  Long-TermThe name of the company associated with the user.
countryCodestring  Long-TermThe two-letter ISO 3166-1 Alpha-2 code for the country of residence (e.g., us).
emailtype  Long-TermThe user's email address for communications from LogScale. Required when using sendInvite.
firstNamestring  Long-TermThe user's actual first name (e.g., Rob). Don't use with fullName.
fullNamestring  Long-TermThe user's full name (e.g., Rob U. Blindman). Don't use if using other name parameters.
isOrgOwnerboolean  Long-TermWhether the user account is the organization owner.
isRootboolean  Long-TermWhether the user account is granted root access.
lastNamestring  Long-TermThe user's actual last name or family name (e.g., Blindman). Don't use with fullName.
picturetype  Long-TermThe file name of an image file for the user.
sendInviteboolean  Long-TermWhether LogScale should send an email providing the user with information to login.
stateCodestring  Long-TermThe two-letter, ISO 3166-2 country sub-division code for the state of residence (e.g., ny).
usernamestringyes Long-TermUser name for the login account.
verificationTokenstring  Long-TermThe verification token for the user account.

As mentioned previously, the addition of a user account and setting of attributes related to that account are made in LogScale, but some values may be captured in return by the application by specifying the desired fields based on the userOrPendingUser schema.

Returned Datatypes

As mentioned previously, the addition of a user account and setting of attributes related to that account are made in LogScale, but some values may be captured in return by the application by specifying the desired fields based on the userOrPendingUser schema. Depending on what is given, this includes two possible specialized datatypes: User or PendingUser

The fields available depend on whether the user has been created, or is instead a pending user. This is determined based on whether the input parameters include not sending an invitation (i.e., sendInvite is set to false). So what's pending is the user acceptance of the invitation.

The schema for the User possibility includes all of the user account attributes. They are listed in the table below, along with their data type and a description of each. Additionally, the Resultant column is used to indicate whether the respective field is always created and filled with a value.

Table: User

ParameterTypeRequiredDefaultStabilityDescription
Some arguments may be required, as indicated in the Required column. For some fields, this column indicates that a result will always be returned for this column.
Table last updated: Sep 30, 2025
allowedAssetActionsBySource(assetId: string, assetType: AssetPermissionsAssetType, searchDomainId: string): [AssetActionsBySource]multipleyes Short-Term

Get allowed asset actions for the user on a specific asset and explain how these actions have been granted.

See AssetPermissionsAssetType , and AssetActionsBySource.

allowedOrganizationActions[OrganizationAction]yes Long-TermReturns the actions the user is allowed to perform in the organization. See OrganizationAction .
allowedSystemActions[SystemAction]yes Long-TermReturns the actions the user is allowed to perform in the system. See SystemAction Table.
companystring  Long-TermThe name of the company for the user account.
countryCodestring  Long-TermThe two-letter ISO 3166-1 Alpha-2 code for the country of residence (e.g., us).
createdAtdatetimeyes Long-TermThe data and time the account was created.
displayNamestringyes Long-TermThe value of the fullName if used, otherwise the username.
emailstring  Long-TermThe user account's email address for communications from LogScale.
firstNamestring  Long-TermThe user's actual first name (e.g., Bob). Don't use with fullName.
fullNamestring  Long-TermThe user's full name (e.g., Bob Smith). Don't use if using other name parameters.
groups[Group]yes Long-TermThe groups of which the user is a member. See Group.
groupSearchDomainRoles[GroupSearchDomainRole]yes Long-TermThe group search domain roles. See GroupSearchDomainRole.
groupsV2(search: string, typeFilter: [PermissionType], limit: integer, skip: integer, searchInRoles: boolean): GroupResultSetTypemultiple  Short-Term

The groups of which the user is a member. This is a preview and subject to change. The default for skip is 0, and limit is 50.

See PermissionType , and GroupResultSetType.

idstringyes Long-TermThe identifier or token for the user.
isOrgRootbooleanyes Long-TermWhether the organization is granted organization ownership.
isRootbooleanyes Long-TermWhether the user account is granted root access.
lastNamestring  Long-TermThe user's actual last name or family name (e.g., Smith). Don't use with fullName.
permissions(viewName: string): [UserPermissions]multipleyes Long-TermPermissions of the user. See UserPermissions.
permissionsPage(search: string, pageNumber: integer, pageSize: integer): UserPermissionsPagemultipleyes Deprecated

A page of user permissions.

See UserPermissionsPage.

This field is no longer used. It will be removed at the earliest in version 1.208.

phoneNumberstring  Long-TermThe telephone number for LogScale to use for telephone text messages.
picturestring  Long-TermFile name of an image file for the account.
rolesV2(search: string, typeFilter: [PermissionType], limit: integer, skip: integer, searchInGroups: boolean): RolesResultSetTypemultiple  Short-Term

The roles assigned to the user through a group. The default for skip is 0, and limit is 50.

See PermissionType , and RolesResultSetType.

searchAssetPermissions(searchFilter: string, skip: integer, limit: integer, orderBy: OrderBy, sortBy: SortBy, assetTypes: [AssetPermissionsAssetType], searchDomainIds: [string], permissions: [AssetAction]): AssetPermissionSearchResultSetmultiple  Short-Term

Search for asset permissions for the user. This is a preview and subject to change. The default for skip is 0, limit is 50, and orderBy is ASC.

See AssetPermissionsAssetType , AssetAction , and AssetPermissionSearchResultSet.

searchDomainRoles(searchDomainId: string): [SearchDomainRole]multiple  Long-TermThe search domain roles assigned to the user. See SearchDomainRole.
searchDomainRolesByName(searchDomainName: string): SearchDomainRolemultipleyes Deprecated

The search domain roles for the user, by name. See SearchDomainRole.

This field is deprecated because when multiple roles per view is enabled, it will return only the first of possibly multiple roles matching the name for the view. Use instead searchDomainRoles or searchDomainRolesBySearchDomainName.

searchDomainRolesBySearchDomainName(searchDomainName: string): [SearchDomainRole]multiple  Long-TermThe search domain roles assigned to the user by search domain name. See SearchDomainRole.
stateCodestring  Long-TermThe two-letter, ISO 3166-2 country sub-division code for the state of residence (e.g., ny).
usernamestringyes Long-TermThe user name for the account.
userOrGroupSearchDomainRoles(search: string, skip: integer, limit: integer): UserOrGroupSearchDomainRoleResultSetmultipleyes Long-Term

The user or group search domain roles. The default for skip is 0, and limit is 50.

See UserOrGroupSearchDomainRoleResultSet.


The schema for the PendingUser possibility includes several fields based on the minimal data collected thus far. They are listed in the table below, along with their data type and a description of each, as well as whether the respective field will always result in it being created and filled with a value.

Table: PendingUser

ParameterTypeRequiredDefaultStabilityDescription
Some arguments may be required, as indicated in the Required column. For some fields, this column indicates that a result will always be returned for this column.
Table last updated: Mar 26, 2025
createdAtlongyes Long-TermThe time the pending user was created.
idstringyes Long-TermThe identifier or token for the pending user.
idpbooleanyes Long-TermWhether IdP is enabled for the organization.
invitedByEmailstringyes Long-TermThe email address of the user that invited the pending user.
invitedByNamestringyes Long-TermThe name of the user that invited the pending user.
newUserEmailstringyes Long-TermThe email of the pending user.
orgNamestringyes Long-TermThe name of the organization for the pending user.
pendingUserStatePendingUserStateyes Long-TermThe current organization state for the user. See PendingUserState.