User Collection

Location /api/apps/{appID}/users
All the users of the current application.

POST

/api/apps/{appID}/users

Description

Create a new user in the current application.

The login name must be unique in the application.

You can also provide the user's email address or phone number instead of the login name. In this case, the verification for the corresponding identifiers must be disabled (i.e., the value of "emailAddressVerificationRequired" / "phoneNumberVerificationRequired" in the application configuration must be set to false). The email address and phone number must be unique in the application once they are verified.

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

The data for creating a new user. In addition to the predefined fields listed in the "Params" section, you can add arbitrary custom fields. Custom fields can have any JSON value, including nested JSONs and arrays. Please note that the custom field has the following restrictions:

  • The whole size of all custom fields (field names + values) should not exceed 63 KB.
  • Custom fields are not indexed, thus you will not be able to query users with these fields.
  • The custom field name cannot start with "_". The field starting with "_" will be ignored and not be stored.
application/json can be used as content-type for the compatibility.

Headers
Name Required? type Description
Authorization Yes string Authorization can be of type Basic or Bearer.
  • Authorization Basic: header for granting an anonymous access.
    • Set a Base64-encoded string of AppID and AppKey concatenated with a colon (APP_ID:APP_KEY).
    • The header should look like:
      Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
  • Authorization Bearer: using Oauth2 Bearer Token.
    • The header should look like:
      Authorization: Bearer ht5fpHQAyrPPwLftK1rAqllv5WNVPCnYfPiCvPocFuQ
Params
Name Required? Type Description
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.
displayName string The display name of the user. The length must be between 1 and 50.
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.
emailAddress string The email address of the user. The maximum length is 200.
phoneNumber string The phone number of the user.
phoneNumberVerified boolean The flag indicating if the phone number is already verified. The field is updatable only with the application administrator's credentials.
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).
Sample Request 
{
  "loginName": "[string]",
  "displayName": "[string]",
  "country": "[string]",
  "locale": "[string]",
  "emailAddress": "[string]",
  "phoneNumber": "[string]",
  "phoneNumberVerified": "[boolean]",
  "password": "[string]"
}
Responses
201

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

The user has been created successfully.
Headers
Name Type Description
Location string URI of the created user.
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.
400

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

The password is too short.
Contents
Name Type Description
message string The error message.
errorCode string Error code "PASSWORD_TOO_SHORT".
minimumLength int The minimum length accepted.
409

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

A user with the same login name, email address, or phone number already exists.
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.

POST

/api/apps/{appID}/users

Description

Create a new user in the current application and obtain an access token of the user.

This API is specially designed for accommodating a pseudo user (i.e. a user without login name and password); none of "loginName", "password", "emailAddress" and "phoneNumber" is mandatory.

This API can also be used for creating a normal user. In this case, you need to set at least one of "loginName", "emailAddress", or "phoneNumber" with the password.

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

The data for creating a new user. In addition to the predefined fields listed in the "Params" section, you can add arbitrary custom fields. Custom fields can have any JSON value, including nested JSONs and arrays. Please note that the custom field has the following restrictions:

  • The whole size of all custom fields (field names + values) should not exceed 63 KB.
  • Custom fields are not indexed, thus you will not be able to query users with these fields.
  • The custom field name cannot start with "_". The field starting with "_" will be ignored and not be stored.

Headers
Name Required? type Description
Authorization Yes string Authorization can be of type Basic or Bearer.
  • Authorization Basic: header for granting an anonymous access.
    • Set a Base64-encoded string of AppID and AppKey concatenated with a colon (APP_ID:APP_KEY).
    • The header should look like:
      Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
  • Authorization Bearer: using Oauth2 Bearer Token.
    • The header should look like:
      Authorization: Bearer ht5fpHQAyrPPwLftK1rAqllv5WNVPCnYfPiCvPocFuQ
Params
Name Required? Type Description
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.
displayName string The display name of the user. The length must be between 1 and 50.
country string The 2-letter country code of the user. It must be be upper-case characters (e.g., JP, US, and CN).
locale string The locale of the user.
emailAddress string The email address of the user. The maximum length is 200.
phoneNumber string The phone number of the user.
phoneNumberVerified boolean The flag indicating if the phone number is already verified. The field is updatable only with the application administrator's credentials.
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).
Sample Request 
{
  "loginName": "[string]",
  "displayName": "[string]",
  "country": "[string]",
  "locale": "[string]",
  "emailAddress": "[string]",
  "phoneNumber": "[string]",
  "phoneNumberVerified": "[boolean]",
  "password": "[string]"
}
Responses
201

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

The user has been created successfully.
Headers
Name Type Description
Location string URI of the created user.
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.
_accessToken string The access token of the user.
_refreshToken string The refresh token for the obtained access token. The refresh token will not be provided when a pseudo user is created.
400

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

The password is too short.
Contents
Name Type Description
message string The error message.
errorCode string Error code "PASSWORD_TOO_SHORT".
minimumLength int The minimum length accepted.
409

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

A user with the same login name, email address, or phone number already exists.
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.