User by ID

Location /api/apps/{appID}/users/{userID}
This resource represents a user belonging to an application in Kii Cloud. The user is accessed by its user ID.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

GET

/api/apps/{appID}/users/{userID}

Description

Retrieve the user information.

Security

An anonymous access to this method is not allowed.

You can retrieve the full user's data if you access this method with the application administrator credentials or with the token of the target user.

If you access this method with the different user's token, the amount of the user information you can retrieve depends on the setting made on the application property "exposeFullUserDataToOthers".

  • You will be able to get the full data if the property is set to "true."
  • You will be able to get only the "userID", "loginName", and "displayName" fields if the property is set to "false" or "null".

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
userID Yes string The ID of the user.
Responses
200

Content-Type application/vnd.kii.UserDataRetrievalResponse+json

The user's data has been retrieved successfully. The body of the response will contain both the predefined and custom fields.
Contents
Name Type Description
userID string The ID of the user.
internalUserID long The internal ID of the user.
loginName string The login name of the user.
displayName string The display name of the user.
country string The country of the user.
locale string The locale of the user.
emailAddress string The email address of the user.
emailAddressVerified boolean The flag indicating if the user's email address is verified.
phoneNumber string The phone number of the user.
phoneNumberVerified boolean The flag indicating if the user's phone number is verified.
_hasPassword boolean The flag indicating if the user has the password.
404

Content-Type application/vnd.kii.UserNotFoundException+json

The user was not found.
Contents
Name Type Description
errorCode string Error code "USER_NOT_FOUND".
message string The error message.
field string The field used for searching the user. This can be the userID or address field.
value string The field value used for searching the user.
appID string The ID of the application.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

An anonymous access was not allowed.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

POST

/api/apps/{appID}/users/{userID}

Description

Modify user's data. You can modify the following fields:

  • country
  • locale
  • displayName
  • password
  • loginName
  • emailAddress
  • phoneNumber
  • custom fields

The predefined fields are modified if they have values in the request. The predefined fields that do not have any value in the request will remain untouched.

The custom fields will always be overwritten by the content in the request. You need to put all custom fields you want to preserve, regardless of if you want to change their field values or not. The fields will be removed otherwise.

This operation has the following limitations:

  • This operation cannot be used for changing the user's current password.
  • You can use this method to set a password to a user who currently does not have any password (i.e. the user is currently a pseudo user, and you want to convert him to a normal user). In this case, you need to provide at least one of loginName, phoneNumber or emailAddress.
  • To set an emailAddress, loginName, and phoneNumber, the user must already have a password. If the user currently does not have any password, a new password must be provided in the same request.

Security

Only the administrator and the user himself can access this method.

Content-Type application/vnd.kii.UserUpdateRequest+json

The data for updating the user.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
userID Yes string The ID of the user.
Params
Name Required? Type Description
country string The 2-letter country code of the user. It must be upper-case characters (e.g., JP, US, and CN).
locale string The locale of the user.
displayName string The display name. The length must be between 1 and 50.
password string The password of the user. The length must be between 4 and 50 characters and must follow the next pattern: \p{Print} (only printable characters).
loginName string The login name of the user. The length must be between 3 and 64, and just allows letters, numbers and '_'. The login name is stored in lowercase.
emailAddress string The email address of the user. The maxium length is 200.
phoneNumber string The phone number of the user.
Sample Request 
{
  "country": "[string]",
  "locale": "[string]",
  "displayName": "[string]",
  "password": "[string]",
  "loginName": "[string]",
  "emailAddress": "[string]",
  "phoneNumber": "[string]"
}
Responses
200

Content-Type application/vnd.kii.UserUpdateResponse+json

The user has been updated successfully.
Contents
Name Type Description
modifiedAt long The modification date of the user in Unix epoch (milliseconds in UTC).
404

Content-Type application/vnd.kii.UserNotFoundException+json

The user was not found.
Contents
Name Type Description
errorCode string Error code "USER_NOT_FOUND".
message string The error message.
field string The field used for searching the user. This can be the userID or address field.
value string The field value used for searching the user.
appID string The ID of the application.
409

Content-Type application/vnd.kii.AddressAlreadyInUseException+json

The loginName is already used by another user, or the phone number or email address is already verified by another user.
Contents
Name Type Description
errorCode string Error code "USER_ALREADY_EXISTS".
message string The error message.
field string The field used to check the user already exists, can be "loginName", "emailAddress" or "phoneNumber".
value string The value of the field.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

An anonymous access or an access by different user was not allowed.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

DELETE

/api/apps/{appID}/users/{userID}

Description

Delete the user from Kii Cloud.

This operation will invalidate all authorization tokens of the user. The operation will also delete all installations of the user.

Security

Only the administrator and the user himself can access this method.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
userID Yes string The ID of the user.
Responses
204

Content-Type (None)

The user has been deleted successfully.
Note This response has no contents.
404

Content-Type application/vnd.kii.UserNotFoundException+json

The user was not found.
Contents
Name Type Description
errorCode string Error code "USER_NOT_FOUND".
message string The error message.
field string The field used for searching the user. This can be the userID or address field.
value string The field value used for searching the user.
appID string The ID of the application.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

An anonymous access or an access by different user was not allowed.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).