1. Overview
This page contains all of the APIs for managing users.
2. Create a User
This API is used to create a new User.
2.1. Request
Create a User with a randomly generated Id
POST /api/user
Create a User with the provided unique Id
POST /api/user/{userId}
userId [UUID] Optional defaults to secure random UUID |
The Id to use for the new User. If not specified a secure random UUID will be generated. |
You must specify either the email or the username or both for the User. Either of these values may be used to uniquely identify the User and may be used to authenticate the User. These fields are marked as optional below, but you must specify at least one of them.
sendSetPasswordEmail [Boolean] Optional defaults to |
Indicates to Passport to send the User an email asking them to set their password. The Email Template that is used is configured in the System Configuration setting for Set Password Email Template.
Available Since 1.21.1
If you have also enabled email verification and do not select to skip verification using the |
skipVerification [Boolean] Optional defaults to |
Indicates to Passport that it should skip email verification even if it is enabled. This is useful for creating admin or internal User accounts. |
user.birthDate [String] Optional |
An |
user.data [Object] Optional |
Object that holds attributes and preferredLanguage. |
user.data.attributes [Object] Optional |
An object that can hold any information about a User that should be persisted. |
user.data.preferredLanguages [Array<String>] Optional |
An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales. |
user.email [String] Optional |
The User’s email address. An email address is a unique in Passport and stored in lower case.
If email is not provided, then the |
user.encryptionScheme [String] Optional defaults to |
The method for encrypting the User’s password. The following encryptors are provided with Passport: You can also create your own password encryptor. See the Password Encryptors section for more information. |
user.expiry [Long] Optional |
The expiration instant of the User’s account. An expired user is not permitted to login. |
user.factor [String] Optional Available Since 1.3.0 |
The factor used by the password encryption scheme. If not provided, the |
user.firstName [String] Optional |
The first name of the User. |
user.fullName [String] Optional |
The User’s full name (as a separate field that is not calculated from firstName and lastName) |
user.imageUrl [String] Optional |
The URL that points to an image file that is the User’s profile image. |
user.lastName [String] Optional |
The User’s last name. |
user.middleName [String] Optional |
The User’s middle name. |
user.mobilePhone [String] Optional |
The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User. |
user.parentId [UUID] Optional |
The Id of this User’s parent. This field forms a parent child relationship that is useful for COPPA and other parental account management features. |
user.parentalConsentType [String] Optional |
The COPPA and EU consent type that was given to the User (assuming the User is a child under 13) by their parent. This implies verifiable parental consent was given or revoked. The possible values are:
When this parameter is not defined no permission has been granted. |
user.password [String] Optional |
The User’s password. |
user.passwordChangeRequired [Boolean] Optional |
Indicates that the User’s password needs to be changed during their next login attempt. |
user.timezone [String] Optional |
The User’s preferred timezone. The format is not enforced, however it is recommended to use a timezone in the TZ format such as
|
users.twoFactorDelivery [String] Optional defaults to |
The User’s preferred delivery for verification codes during a two factor login request. The possible values are:
When using |
user.twoFactorEnabled [Boolean] Optional |
Determines if the User has two factor authentication enabled for their account or not. See the Enable Two Factor and Disable Two Factor APIs as an alternative to performing this action using the User API. |
user.twoFactorSecret [String] Optional |
The secret used to generate Two Factor verification codes.
You may optionally use value provided in the
Unless you are using
When using |
user.username [String] Optional |
The username of the User. The username is stored and returned as a case sensitive value, however a username is considered unique regardless of the case.
If username is not provided, then the |
user.usernameStatus [String] Optional |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
This state is managed by CleanSpeak, it may be changed by setting it on this request. |
{
"user": {
"active": true,
"birthDate": "1976-05-30",
"childIds": [
"00000000-0000-0001-0000-000000000001",
"00000000-0000-0001-0000-000000000002"
],
"data": {
"attributes": {
"displayName": "Johnny Boy",
"favoriteColors": [
"Red",
"Blue"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"email": "example@inversoft.com",
"encryptionScheme": "salted-sha256",
"factor": 24000,
"expiry": 1571786483322,
"firstName": "John",
"fullName": "John Doe",
"imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
"lastName": "Doe",
"middleName": "William",
"mobilePhone": "303-555-1234",
"passwordChangeRequired": false,
"timezone": "America/Denver",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123"
}
}
2.2. Response
The response for this API contains the User that was just created. The password, salt and other sensitive fields will not be returned on the API response.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
429 |
The number of users allowed by your license has been exceeded. Contact sales@inversoft.com for assistance. Starting in version 1.19.0 this status code will not be returned, instead the number of users allowed by your license will be soft enforced. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
504 |
One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the Passport log files. |
user.active [Boolean] |
True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login. |
user.birthDate [String] |
The User’s birthdate formatted as |
user.childIds [Array<UUID>] |
A list of Ids for the child account’s that this User is the parent of. |
user.cleanSpeakId [UUID] |
This Id is used by Passport when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
user.data [Object] |
Object that holds attributes and preferredLanguage. |
user.data.attributes [Object] |
An object that can hold any information about the User that should be persisted. |
user.data.preferredLanguages [Array<String>] |
An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales. |
user.email [String] |
The User’s email address. |
user.expiry [Long] |
The expiration instant of the User’s account. An expired user is not permitted to login. |
user.firstName [String] |
The first name of the User. |
user.fullName [String] |
The User’s full name (as a separate field that is not calculated from firstName and lastName) |
user.id [UUID] |
The User’s unique Id. |
user.imageUrl [String] |
The URL that points to an image file that is the User’s profile image. |
user.insertInstant [Long] Available Since 1.7.0 |
The instant when user was created. |
user.lastLoginInstant [Long] |
The instant when the User logged in last. |
user.lastName [String] |
The User’s last name. |
user.middleName [String] |
The User’s middle name. |
user.mobilePhone [String] |
The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User. |
user.parentId [UUID] |
The Id of this User’s parent. This field forms a parent child relationship that is useful for COPPA and other parental account management features. |
user.parentalConsentType [String] |
The COPPA and EU consent type that was given to the User (assuming the User is a child under 13) by their parent. This implies verifiable parental consent was given or revoked. The possible values are:
When this parameter is not defined no permission has been granted. |
user.passwordChangeRequired [Boolean] |
Indicates that the User’s password needs to be changed during their next login attempt. |
user.passwordLastUpdateInstant [Long] |
The instant that the User last changed their password. |
user.registrations [Array] |
The list of registrations for the User. |
user.registrations |
The Id of the Application that this registration is for. |
user.registrations |
This Id is used by Passport when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
user.registrations |
Object that holds attributes and preferredLanguage for this registration. |
user.registrations |
An object that can hold any information about the User for this registration that should be persisted. |
user.registrations |
An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text. |
user.registrations |
The Id of this registration. |
user.registrations |
The instant that this registration was created. |
user.registrations |
The instant that the User last logged into the Application for this registration. |
user.registrations |
The list of roles that the User has for this registration. |
user.registrations |
The username of the User for this registration only. |
user.registrations |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
user.timezone [String] |
The User’s preferred timezone. |
users.twoFactorDelivery [String] Available Since 1.16.0 |
The User’s preferred delivery for verification codes during a two factor login request. The possible values are:
|
user.twoFactorEnabled [Boolean] |
Determines if the User has two factor authentication enabled for their account or not. |
user.username [String] |
The username of the User. |
user.usernameStatus [String] |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
user.verified [Boolean] |
Whether or not the User’s email has been verified. |
{
"user": {
"active": true,
"birthDate": "1976-05-30",
"childIds": [
"00000000-0000-0001-0000-000000000001",
"00000000-0000-0001-0000-000000000002"
],
"data": {
"attributes": {
"displayName": "Johnny Boy",
"favoriteColors": [
"Red",
"Blue"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"email": "example@inversoft.com",
"expiry": 1571786483322,
"firstName": "John",
"fullName": "John Doe",
"id": "00000000-0000-0001-0000-000000000000",
"imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
"lastLoginInstant": 1471786483322,
"lastName": "Doe",
"middleName": "William",
"mobilePhone": "303-555-1234",
"passwordChangeRequired": false,
"passwordLastUpdateInstant": 1471786483322,
"registrations": [
{
"applicationId": "10000000-0000-0002-0000-000000000001",
"data": {
"attributes": {
"displayName": "Johnny",
"favoriteSports": [
"Football",
"Basketball"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"id": "00000000-0000-0002-0000-000000000000",
"insertInstant": 1446064706250,
"lastLoginInstant": 1456064601291,
"roles": [
"user",
"community_helper"
],
"username": "johnny123",
"usernameStatus": "ACTIVE"
}
],
"timezone": "America/Denver",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123",
"verified": true
}
}
3. Retrieve a User
This API is used to retrieve the information about a single User. You can use the User’s Id, username or email address to retrieve the User. The Id is specified on the URI and the username or email are specified as URL parameters.
3.1. Request
GET /api/user/{userId}
userId [UUID] Required |
The unique Id of the User to retrieve. |
GET /api/user?loginId={loginId}
loginId [String] Required Available Since 1.9.4 |
The unique Id of the User to retrieve. The loginId can be either the email or username. |
GET /api/user?email={email}
email [String] Required |
The email of the User to retrieve. |
GET /api/user?username={username}
username [String] Required |
The username of the User to retrieve. |
Retrieve a User by Change Password Id
GET /api/user?changePasswordId={changePasswordId}
changePasswordId [String] Required Available Since 1.16.0 |
The change password Id associated with the user when the Forgot Password workflow has been started. |
Retrieve a User by Email Verification Id
GET /api/user?verificationId={verificationId}
verificationId [String] Required Available Since 1.13.1 |
The verification Id associated with the user when the Email verification process has been started. |
GET /api/user
Available Since Version 1.6.2 |
3.2. Response
The response for this API contains the User.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
404 |
The object you requested doesn’t exist. The response will be empty. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
user.active [Boolean] |
True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login. |
user.birthDate [String] |
The User’s birthdate formatted as |
user.childIds [Array<UUID>] |
A list of Ids for the child account’s that this User is the parent of. |
user.cleanSpeakId [UUID] |
This Id is used by Passport when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
user.data [Object] |
Object that holds attributes and preferredLanguage. |
user.data.attributes [Object] |
An object that can hold any information about the User that should be persisted. |
user.data.preferredLanguages [Array<String>] |
An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales. |
user.email [String] |
The User’s email address. |
user.expiry [Long] |
The expiration instant of the User’s account. An expired user is not permitted to login. |
user.firstName [String] |
The first name of the User. |
user.fullName [String] |
The User’s full name (as a separate field that is not calculated from firstName and lastName) |
user.id [UUID] |
The User’s unique Id. |
user.imageUrl [String] |
The URL that points to an image file that is the User’s profile image. |
user.insertInstant [Long] Available Since 1.7.0 |
The instant when user was created. |
user.lastLoginInstant [Long] |
The instant when the User logged in last. |
user.lastName [String] |
The User’s last name. |
user.middleName [String] |
The User’s middle name. |
user.mobilePhone [String] |
The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User. |
user.parentId [UUID] |
The Id of this User’s parent. This field forms a parent child relationship that is useful for COPPA and other parental account management features. |
user.parentalConsentType [String] |
The COPPA and EU consent type that was given to the User (assuming the User is a child under 13) by their parent. This implies verifiable parental consent was given or revoked. The possible values are:
When this parameter is not defined no permission has been granted. |
user.passwordChangeRequired [Boolean] |
Indicates that the User’s password needs to be changed during their next login attempt. |
user.passwordLastUpdateInstant [Long] |
The instant that the User last changed their password. |
user.registrations [Array] |
The list of registrations for the User. |
user.registrations |
The Id of the Application that this registration is for. |
user.registrations |
This Id is used by Passport when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
user.registrations |
Object that holds attributes and preferredLanguage for this registration. |
user.registrations |
An object that can hold any information about the User for this registration that should be persisted. |
user.registrations |
An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text. |
user.registrations |
The Id of this registration. |
user.registrations |
The instant that this registration was created. |
user.registrations |
The instant that the User last logged into the Application for this registration. |
user.registrations |
The list of roles that the User has for this registration. |
user.registrations |
The username of the User for this registration only. |
user.registrations |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
user.timezone [String] |
The User’s preferred timezone. |
users.twoFactorDelivery [String] Available Since 1.16.0 |
The User’s preferred delivery for verification codes during a two factor login request. The possible values are:
|
user.twoFactorEnabled [Boolean] |
Determines if the User has two factor authentication enabled for their account or not. |
user.username [String] |
The username of the User. |
user.usernameStatus [String] |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
user.verified [Boolean] |
Whether or not the User’s email has been verified. |
{
"user": {
"active": true,
"birthDate": "1976-05-30",
"childIds": [
"00000000-0000-0001-0000-000000000001",
"00000000-0000-0001-0000-000000000002"
],
"data": {
"attributes": {
"displayName": "Johnny Boy",
"favoriteColors": [
"Red",
"Blue"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"email": "example@inversoft.com",
"expiry": 1571786483322,
"firstName": "John",
"fullName": "John Doe",
"id": "00000000-0000-0001-0000-000000000000",
"imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
"lastLoginInstant": 1471786483322,
"lastName": "Doe",
"middleName": "William",
"mobilePhone": "303-555-1234",
"passwordChangeRequired": false,
"passwordLastUpdateInstant": 1471786483322,
"registrations": [
{
"applicationId": "10000000-0000-0002-0000-000000000001",
"data": {
"attributes": {
"displayName": "Johnny",
"favoriteSports": [
"Football",
"Basketball"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"id": "00000000-0000-0002-0000-000000000000",
"insertInstant": 1446064706250,
"lastLoginInstant": 1456064601291,
"roles": [
"user",
"community_helper"
],
"username": "johnny123",
"usernameStatus": "ACTIVE"
}
],
"timezone": "America/Denver",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123",
"verified": true
}
}
4. Update a User
This API is used to update an existing User. You must specify the Id of the User you are updating on the URI. You must specify all of the properties of the User when calling this API. This API doesn’t merge the existing User and your new data. It replaces the existing User with your new data.
If you specify a new password for the User, it will be encrypted and stored. However, if you do not provide a new password, the User’s old password will be preserved. This is the only field that is merged during an update.
4.1. Request
Update the User with the given Id
PUT /api/user/{userId}
userId [UUID] Required |
The Id of the User to update. |
You must specify either the email or the username or both for the User. Either of these values may be used to uniquely identify the User and may be used to authenticate the User. These fields are marked as optional below, but you must specify at least one of them.
skipVerification [Boolean] Optional defaults to |
Indicates to Passport that it should skip email verification even if it is enabled. This is useful for creating admin or internal User accounts. |
user.birthDate [String] Optional |
An |
user.data [Object] Optional |
Object that holds attributes and preferredLanguage. |
user.data.attributes [Object] Optional |
An object that can hold any information about a User that should be persisted. |
user.data.preferredLanguages [Array<String>] Optional |
An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales. |
user.email [String] Optional |
The User’s email address. An email address is a unique in Passport and stored in lower case.
If email is not provided, then the |
user.encryptionScheme [String] Optional defaults to |
The method for encrypting the User’s password. The following encryptors are provided with Passport:
This field is ignored unless the You can also create your own password encryptor. See the Password Encryptors section for more information. |
user.expiry [Long] Optional |
The expiration instant of the User’s account. An expired user is not permitted to login. |
user.factor [String] Optional Available Since 1.3.0 |
The factor used by the password encryption scheme. If not provided, the |
user.firstName [String] Optional |
The first name of the User. |
user.fullName [String] Optional |
The User’s full name (as a separate field that is not calculated from firstName and lastName) |
user.imageUrl [String] Optional |
The URL that points to an image file that is the User’s profile image. |
user.lastName [String] Optional |
The User’s last name. |
user.middleName [String] Optional |
The User’s middle name. |
user.mobilePhone [String] Optional |
The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User. |
user.parentId [UUID] Optional |
The Id of this User’s parent. This field forms a parent child relationship that is useful for COPPA and other parental account management features. |
user.parentalConsentType [String] Optional |
The COPPA and EU consent type that was given to the User (assuming the User is a child under 13) by their parent. This implies verifiable parental consent was given or revoked. The possible values are:
When this parameter is not defined no permission has been granted. |
user.password [String] Optional |
The User’s password. |
user.passwordChangeRequired [Boolean] Optional |
Indicates that the User’s password needs to be changed during their next login attempt. |
user.timezone [String] Optional |
The User’s preferred timezone. The format is not enforced, however it is recommended to use a timezone in the TZ format such as
|
users.twoFactorDelivery [String] Optional defaults to |
The User’s preferred delivery for verification codes during a two factor login request. The possible values are:
When using If Two Factor authentication is already enabled for this user, the delivery may not be modified. In order to change the delivery type you must first disable Two Factor authentication and re-enable with a new delivery type. |
user.twoFactorEnabled [Boolean] Optional |
Determines if the User has two factor authentication enabled for their account or not. If Two Factor authentication is already enabled for this user disabling Two Factor authentication will reset the delivery type and secret. See the Enable Two Factor and Disable Two Factor APIs as an alternative to performing this action using the User API. |
user.twoFactorSecret [String] Optional |
The secret used to generate Two Factor verification codes.
You may optionally use value provided in the
Unless you are using
When using If Two Factor authentication is already enabled for this user, the secret may not be modified. In order to change the secret you must first disable Two Factor authentication and re-enable with a new secret. |
user.username [String] Optional |
The username of the User. The username is stored and returned as a case sensitive value, however a username is considered unique regardless of the case.
If username is not provided, then the |
user.usernameStatus [String] Optional |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
This state is managed by CleanSpeak, it may be changed by setting it on this request. |
user.verificationId [String] Optional Available Since 1.5.2 Deprecated |
The verification Id that may be used on the Change a User’s Password API. It is preferred to use the Id returned on the Start Forgot Password Workflow API. This parameter may be used if a specific value is required to integrate with 3rd party email or SMS notification systems.
Once available use the |
{
"user": {
"active": true,
"birthDate": "1976-05-30",
"childIds": [
"00000000-0000-0001-0000-000000000001",
"00000000-0000-0001-0000-000000000002"
],
"data": {
"attributes": {
"displayName": "Johnny Boy",
"favoriteColors": [
"Red",
"Blue"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"email": "example@inversoft.com",
"encryptionScheme": "salted-sha256",
"factor": 24000,
"expiry": 1571786483322,
"firstName": "John",
"fullName": "John Doe",
"imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
"lastName": "Doe",
"middleName": "William",
"mobilePhone": "303-555-1234",
"passwordChangeRequired": false,
"timezone": "America/Denver",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123"
}
}
4.2. Response
The response for this API contains the User that was updated. The password hash and other sensitive fields are never returned on the API response.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
404 |
The object you are trying to updated doesn’t exist. The response will be empty. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
504 |
One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the Passport log files. |
user.active [Boolean] |
True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login. |
user.birthDate [String] |
The User’s birthdate formatted as |
user.childIds [Array<UUID>] |
A list of Ids for the child account’s that this User is the parent of. |
user.cleanSpeakId [UUID] |
This Id is used by Passport when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
user.data [Object] |
Object that holds attributes and preferredLanguage. |
user.data.attributes [Object] |
An object that can hold any information about the User that should be persisted. |
user.data.preferredLanguages [Array<String>] |
An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales. |
user.email [String] |
The User’s email address. |
user.expiry [Long] |
The expiration instant of the User’s account. An expired user is not permitted to login. |
user.firstName [String] |
The first name of the User. |
user.fullName [String] |
The User’s full name (as a separate field that is not calculated from firstName and lastName) |
user.id [UUID] |
The User’s unique Id. |
user.imageUrl [String] |
The URL that points to an image file that is the User’s profile image. |
user.insertInstant [Long] Available Since 1.7.0 |
The instant when user was created. |
user.lastLoginInstant [Long] |
The instant when the User logged in last. |
user.lastName [String] |
The User’s last name. |
user.middleName [String] |
The User’s middle name. |
user.mobilePhone [String] |
The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User. |
user.parentId [UUID] |
The Id of this User’s parent. This field forms a parent child relationship that is useful for COPPA and other parental account management features. |
user.parentalConsentType [String] |
The COPPA and EU consent type that was given to the User (assuming the User is a child under 13) by their parent. This implies verifiable parental consent was given or revoked. The possible values are:
When this parameter is not defined no permission has been granted. |
user.passwordChangeRequired [Boolean] |
Indicates that the User’s password needs to be changed during their next login attempt. |
user.passwordLastUpdateInstant [Long] |
The instant that the User last changed their password. |
user.registrations [Array] |
The list of registrations for the User. |
user.registrations |
The Id of the Application that this registration is for. |
user.registrations |
This Id is used by Passport when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
user.registrations |
Object that holds attributes and preferredLanguage for this registration. |
user.registrations |
An object that can hold any information about the User for this registration that should be persisted. |
user.registrations |
An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text. |
user.registrations |
The Id of this registration. |
user.registrations |
The instant that this registration was created. |
user.registrations |
The instant that the User last logged into the Application for this registration. |
user.registrations |
The list of roles that the User has for this registration. |
user.registrations |
The username of the User for this registration only. |
user.registrations |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
user.timezone [String] |
The User’s preferred timezone. |
users.twoFactorDelivery [String] Available Since 1.16.0 |
The User’s preferred delivery for verification codes during a two factor login request. The possible values are:
|
user.twoFactorEnabled [Boolean] |
Determines if the User has two factor authentication enabled for their account or not. |
user.username [String] |
The username of the User. |
user.usernameStatus [String] |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
user.verified [Boolean] |
Whether or not the User’s email has been verified. |
{
"user": {
"active": true,
"birthDate": "1976-05-30",
"childIds": [
"00000000-0000-0001-0000-000000000001",
"00000000-0000-0001-0000-000000000002"
],
"data": {
"attributes": {
"displayName": "Johnny Boy",
"favoriteColors": [
"Red",
"Blue"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"email": "example@inversoft.com",
"expiry": 1571786483322,
"firstName": "John",
"fullName": "John Doe",
"id": "00000000-0000-0001-0000-000000000000",
"imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
"lastLoginInstant": 1471786483322,
"lastName": "Doe",
"middleName": "William",
"mobilePhone": "303-555-1234",
"passwordChangeRequired": false,
"passwordLastUpdateInstant": 1471786483322,
"registrations": [
{
"applicationId": "10000000-0000-0002-0000-000000000001",
"data": {
"attributes": {
"displayName": "Johnny",
"favoriteSports": [
"Football",
"Basketball"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"id": "00000000-0000-0002-0000-000000000000",
"insertInstant": 1446064706250,
"lastLoginInstant": 1456064601291,
"roles": [
"user",
"community_helper"
],
"username": "johnny123",
"usernameStatus": "ACTIVE"
}
],
"timezone": "America/Denver",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123",
"verified": true
}
}
5. Delete a User
This API is used to delete a User. You must specify the Id of the User on the URI. You can also specify whether or not the User is soft or hard deleted. Soft deleted Users are marked as inactive but not deleted from Passport.
5.1. Request
Deactivate a User (Soft Delete)
DELETE /api/user/{userId}
DELETE /api/user/{userId}?hardDelete=true
userId [UUID] Required |
The Id of the User to delete. |
hardDelete [Boolean] Optional defaults to |
To Permanently delete a user from Passport set this value to |
5.2. Response
This API does not return a JSON response body.
Code | Description |
---|---|
200 |
The request was successful. The response will be empty. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
404 |
The object you are trying to delete doesn’t exist. The response will be empty. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
504 |
One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the Passport log files. |
6. Bulk Delete Users
Available Since Version 1.9.4 |
This API is used to delete multiple users in a single request.
6.1. Request
DELETE /api/user/bulk?userId={userId}&userId={userId}
DELETE /api/user/bulk?userId={userId}&userId={userId}&hardDelete=true
userId [UUID] Required |
The Id of the User to delete. Repeat this parameter for each user to be deleted. |
hardDelete [Boolean] Optional defaults to |
To Permanently delete a user from Passport set this value to |
Bulk delete using the request body. This allows for larger requests than are possible using request parameters.
DELETE /api/user/bulk
Available Since Version 1.13.0 |
hardDelete [Boolean] Optional defaults to |
To Permanently delete a user from Passport set this value to |
userIds [Array] Required |
An array of User Ids to delete. |
{
"hardDelete": false,
"userIds": [
"5c1dc1a8-2fc8-4ae0-9372-e994be0f4341",
"dbf59ee1-2d24-4ea0-b977-2b6e2a5350bf",
"3e74294d-7de7-45a4-9592-4a198ddbdc73",
"cfaf34a0-aa66-4d3a-af14-6dbc5f9fb577",
"a2eb9268-e6f1-45f4-8eaa-50c0154983fe",
"b1b42d6b-3b44-47fb-bb32-26e0c71c62d3",
"8c91cb08-27df-4725-b3a8-98631bc8d9af",
"54df878b-c0a1-4951-a63a-3cf2f97edd17",
"946b3deb-25a5-4155-b137-bb5202d2ac98"
]
}
6.2. Response
This API does not return a JSON response body.
Code | Description |
---|---|
200 |
The request was successful. The response will be empty. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
504 |
One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the Passport log files. |
7. Reactivate a User
This API is used to reactivate an inactive Users. You must specify the Id of the User on the URI.
7.1. Request
PUT /api/user/{userId}?reactivate=true
userId [UUID] Required |
The Id of the User to reactivate. |
7.2. Response
The response for this API contains the information for the User that was reactivated.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
404 |
The object you are trying to updated doesn’t exist. The response will be empty. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
504 |
One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the Passport log files. |
user.active [Boolean] |
True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login. |
user.birthDate [String] |
The User’s birthdate formatted as |
user.childIds [Array<UUID>] |
A list of Ids for the child account’s that this User is the parent of. |
user.cleanSpeakId [UUID] |
This Id is used by Passport when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
user.data [Object] |
Object that holds attributes and preferredLanguage. |
user.data.attributes [Object] |
An object that can hold any information about the User that should be persisted. |
user.data.preferredLanguages [Array<String>] |
An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales. |
user.email [String] |
The User’s email address. |
user.expiry [Long] |
The expiration instant of the User’s account. An expired user is not permitted to login. |
user.firstName [String] |
The first name of the User. |
user.fullName [String] |
The User’s full name (as a separate field that is not calculated from firstName and lastName) |
user.id [UUID] |
The User’s unique Id. |
user.imageUrl [String] |
The URL that points to an image file that is the User’s profile image. |
user.insertInstant [Long] Available Since 1.7.0 |
The instant when user was created. |
user.lastLoginInstant [Long] |
The instant when the User logged in last. |
user.lastName [String] |
The User’s last name. |
user.middleName [String] |
The User’s middle name. |
user.mobilePhone [String] |
The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User. |
user.parentId [UUID] |
The Id of this User’s parent. This field forms a parent child relationship that is useful for COPPA and other parental account management features. |
user.parentalConsentType [String] |
The COPPA and EU consent type that was given to the User (assuming the User is a child under 13) by their parent. This implies verifiable parental consent was given or revoked. The possible values are:
When this parameter is not defined no permission has been granted. |
user.passwordChangeRequired [Boolean] |
Indicates that the User’s password needs to be changed during their next login attempt. |
user.passwordLastUpdateInstant [Long] |
The instant that the User last changed their password. |
user.registrations [Array] |
The list of registrations for the User. |
user.registrations |
The Id of the Application that this registration is for. |
user.registrations |
This Id is used by Passport when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
user.registrations |
Object that holds attributes and preferredLanguage for this registration. |
user.registrations |
An object that can hold any information about the User for this registration that should be persisted. |
user.registrations |
An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text. |
user.registrations |
The Id of this registration. |
user.registrations |
The instant that this registration was created. |
user.registrations |
The instant that the User last logged into the Application for this registration. |
user.registrations |
The list of roles that the User has for this registration. |
user.registrations |
The username of the User for this registration only. |
user.registrations |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
user.timezone [String] |
The User’s preferred timezone. |
users.twoFactorDelivery [String] Available Since 1.16.0 |
The User’s preferred delivery for verification codes during a two factor login request. The possible values are:
|
user.twoFactorEnabled [Boolean] |
Determines if the User has two factor authentication enabled for their account or not. |
user.username [String] |
The username of the User. |
user.usernameStatus [String] |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
user.verified [Boolean] |
Whether or not the User’s email has been verified. |
{
"user": {
"active": true,
"birthDate": "1976-05-30",
"childIds": [
"00000000-0000-0001-0000-000000000001",
"00000000-0000-0001-0000-000000000002"
],
"data": {
"attributes": {
"displayName": "Johnny Boy",
"favoriteColors": [
"Red",
"Blue"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"email": "example@inversoft.com",
"expiry": 1571786483322,
"firstName": "John",
"fullName": "John Doe",
"id": "00000000-0000-0001-0000-000000000000",
"imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
"lastLoginInstant": 1471786483322,
"lastName": "Doe",
"middleName": "William",
"mobilePhone": "303-555-1234",
"passwordChangeRequired": false,
"passwordLastUpdateInstant": 1471786483322,
"registrations": [
{
"applicationId": "10000000-0000-0002-0000-000000000001",
"data": {
"attributes": {
"displayName": "Johnny",
"favoriteSports": [
"Football",
"Basketball"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"id": "00000000-0000-0002-0000-000000000000",
"insertInstant": 1446064706250,
"lastLoginInstant": 1456064601291,
"roles": [
"user",
"community_helper"
],
"username": "johnny123",
"usernameStatus": "ACTIVE"
}
],
"timezone": "America/Denver",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123",
"verified": true
}
}
8. Import Users
This API is used to bulk import multiple Users into Passport. Each User must have at least an email or a username. This request is useful for migrating data from an existing database into Passport. Additionally, you can provide an Id for each User inside the JSON User object of the request body.
8.1. Request
POST /api/user/import
You must provide either the email or the username field for each User. This will be used to authenticate the User and is also the User’s unique identifier. These fields are marked as optional below, but you must provide one of them.
encryptionScheme [String] Optional Available Since 1.9.4 |
The encryption scheme used to encrypt plaintext passwords encountered in the request. If this value is omitted the system configured value will be used. The following encryptors are provided with Passport: |
||
factor [Integer] Optional Available Since 1.9.4 |
The factor used to encrypt plaintext passwords encountered in the request. If this value is omitted the system configured value will be used. |
||
users [Array] Required |
The list of Users to import. |
||
users |
True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login. Generally this should be set to |
||
users |
|
||
users |
Object that defines the user data. |
||
users |
An object that can hold any information about a User that should be persisted. |
||
users |
An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales. |
||
users |
The User’s email address. |
||
users |
The method for encrypting the User’s password. If the password value is already encrypted this value is required. Omitting this value indicates the password is in plain text and it will be encrypted using the default password encryptor.
The following encryptors are provided with Passport: If you don’t see the scheme needed for importing your existing password you can also create your own password encryptor or we can build it for you. See the Password Encryptors section for more information. |
||
users |
The expiration instant of the User’s account. After this instant is reached, the User’s account will automatically be deactivated. |
||
users |
The factor used by the password encryption scheme. If omitted the factor will determined either by the system configured factor or the default value defined by the
The factor will generally be used as an iteration count to generate the hash. The actual use of this value is up to the |
||
users |
The first name of the User. |
||
users |
The User’s full name (as a separate field that is not calculated from firstName and lastName) |
||
users |
The Id of the User. If not specified a secure random UUID will be generated. |
||
users |
The URL that points to an image file that is the User’s profile image. |
||
users |
The instant when user was created. |
||
users |
The User’s last name. |
||
users |
The User’s middle name. |
||
users |
The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User. |
||
users |
The Id of this User’s parent. This field forms a parent child relationship that is useful for COPPA and other parental account management features. |
||
users |
The COPPA and EU consent type that was given to the User (assuming the User is a child under 13) by their parent. This implies verifiable parental consent was given or revoked. The possible values are:
When this parameter is not defined no permission has been granted. |
||
users |
The User’s password. Required if |
||
users |
Indicates that the User’s password needs to be changed during the next login attempt. |
||
users |
Indicates that last instant the password was changed.
If
Note that if you have enabled password expiration or plan to do so in the future and you set this value to |
||
users |
The list of registrations for the User. |
||
users |
The Id of the Application that this registration is for. |
||
users |
This Id is used by Passport when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
||
users |
Object that holds attributes and preferredLanguage for this registration. |
||
users |
An object that can hold any information about the User for this registration that should be persisted. |
||
users |
An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text. See Locales. |
||
users |
The Id of this registration. If not specified a secure random UUID will be generated. |
||
users |
The instant that this registration was created. |
||
users |
The instant that the User last logged into the Application for this registration. |
||
users |
The list of roles that the User has for this registration. |
||
users |
The username of the User for this registration only. |
||
users |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
This state is managed by CleanSpeak, it may be changed by setting it on this request. |
||
users |
The User’s password salt. Required if |
||
users |
The User’s tenant Id. If more than one tenant exists and you do not provide the
When an API key is used that is locked to a Tenant or the tenant |
||
users |
The User’s preferred timezone. This can be used as a default to display instants. It is recommended that you allow users to change this on a per-session basis. |
||
users |
The User’s preferred delivery for verification codes during a two factor login request. The possible values are:
When using |
||
users |
Determines if the User has two factor authentication enabled for their account or not. See the Enable Two Factor and Disable Two Factor APIs as an alternative to performing this action using the User API. |
||
users |
The secret used to generate Two Factor verification codes.
You may optionally use value provided in the
Unless you are using
When using |
||
users |
The username of the User. |
||
users |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
This state is managed by CleanSpeak, it may be changed by setting it on this request. |
||
validateDbConstraints [Boolean] Optional defaults to |
Set this value to
The import request is intended to be used to populate the initial set of users, this means Passport does not expect to find duplicate users in the database. If a duplicate is encountered a
If you intend to use this API with existing users in Passport set this value to
Setting this value to |
{
"users": [
{
"active": true,
"birthDate": "1976-05-30",
"childIds": [
"00000000-0000-0001-0000-000000000001",
"00000000-0000-0001-0000-000000000002"
],
"data": {
"attributes": {
"displayName": "Johnny Boy",
"favoriteColors": [
"Red",
"Blue"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"email": "example@inversoft.com",
"encryptionScheme": "salted-sha256",
"expiry": 1571786483322,
"factor": 24000,
"firstName": "John",
"fullName": "John Doe",
"imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
"insertInstant": 1331449200000,
"lastName": "Doe",
"middleName": "William",
"mobilePhone": "303-555-1234",
"password": "5ac152b6f8bdb8bb12959548d542cb237c4a730064bf88bbb8dd6e204912baad",
"passwordChangeRequired": false,
"registrations": [
{
"applicationId": "00000000-0000-0000-0000-000000000002",
"data": {
"attributes": {
"birthplace": "Bremen"
},
"preferredLanguages": ["de"]
},
"insertInstant": 1331449200000,
"roles": ["moderator"],
"username": "Mausebär"
}
],
"salt": "47bafdd3-b99d-4ffd-a5be-e414c80905f0",
"timezone": "America/Denver",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123"
}
]
}
8.2. Response
Only a status code is available on the Import API, no JSON body will be returned.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
504 |
One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the Passport log files. |
9. Search for Users
This API is used to search for Users.
9.1. Request
GET /api/user/search?ids={uuid}&ids={uuid}
Search for Users by a query string
GET /api/user/search?queryString={queryString}
Search for Users by a query string and sort the response
GET /api/user/search?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}
ids [UUID] Optional |
The list of User Ids to lookup. By specifying this URL parameter multiple times you can lookup multiple Users. |
numberOfResults [Integer] Optional defaults to 20 |
The number of search results to return. Used for pagination. |
queryString [String] Optional |
The Elastic Search query string that used to search for Users. |
startRow [Integer] Optional defaults to 0 |
The start row within the search results to return. Used for pagination. |
sortFields [Array] Optional Availale Since 1.8.0 |
An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output. |
sortFields |
The value to substitute if this field is not defined. Two special values may be used:
|
sortFields |
The name of the field to sort. Due to how the search index is structured not all fields on the user are sortable. The following field names are supported.
|
sortFields |
The order to sort the specified field. Possible values are:
|
9.2. Response
The response contains the User objects that were found as part of the lookup or search.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
404 |
The object you requested doesn’t exist. The response will be empty. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
users [Array] |
The list of Users. |
users |
True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login. |
users |
YYYY-MM-DD formatted date of the User’s birth. |
users |
A list of Ids for the child account’s that this User is the parent of. |
users |
This Id is used by Passport when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
users |
Object that holds attributes and preferredLanguage. |
users |
An object that can hold any information about the User that should be persisted. |
users |
An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales. |
users |
The User’s email address. |
users |
The expiration instant of the User’s account. After this instant is reached, the User’s account will automatically be deactivated. |
users |
The first name of the User. |
users |
The User’s full name (as a separate field that is not calculated from firstName and lastName) |
users |
The User’s unique Id. |
users |
The URL that points to an image file that is the User’s profile image. |
users |
The instant when the User logged in last. |
users |
The User’s last name. |
users |
The User’s middle name. |
users |
The User’s mobile phone number. This is useful is you will be sending push notifications or SMS messages to the User. |
users |
The Id of this User’s parent. This field forms a parent child relationship that is useful for COPPA and other parental account management features. |
users |
The COPPA and EU consent type that was given to the User (assuming the User is a child under 13) by their parent. This implies verifiable parental consent was given or revoked. The possible values are:
When this parameter is not defined no permission has been granted. |
users |
Indicates that the User’s password needs to be changed during their next login attempt. |
users |
The instant that the User last changed their password. |
users |
The list of registrations for the User. |
users |
The Id of the Application that this registration is for. |
users |
This Id is used by Passport when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak. |
users |
Object that holds attributes and preferredLanguage for this registration. |
users |
An object that can hold any information about the User for this registration that should be persisted. |
users |
An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text. See Locales. |
users |
The Id of this registration. |
users |
The instant that this registration was created. |
users |
The instant that the User last logged into the Application for this registration. |
users |
The list of roles that the User has for this registration. |
users |
The username of the User for this registration only. |
users |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
users |
This value indicates if this User’s registration has been verified. |
users |
The User’s preferred timezone. This can be used as a default to display instants. It is recommended that you allow User’s to change this per-session. |
users |
The User’s preferred delivery for verification codes during a two factor login request. The possible values are:
|
users |
Determines if the User has two factor authentication enabled for their account or not. |
users |
The username of the User. |
users |
The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:
If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. |
users |
Whether or not the User’s email has been verified. |
{
"users": [
{
"active": true,
"birthDate": "1976-05-30",
"childIds": [
"00000000-0000-0001-0000-000000000001",
"00000000-0000-0001-0000-000000000002"
],
"data": {
"attributes": {
"displayName": "Johnny Boy",
"favoriteColors": [
"Red",
"Blue"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"email": "example@inversoft.com",
"expiry": 1571786483322,
"firstName": "John",
"fullName": "John Doe",
"id": "00000000-0000-0001-0000-000000000000",
"imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
"lastLoginInstant": 1471786483322,
"lastName": "Doe",
"middleName": "William",
"mobilePhone": "303-555-1234",
"passwordChangeRequired": false,
"passwordLastUpdateInstant": 1471786483322,
"registrations": [
{
"applicationId": "10000000-0000-0002-0000-000000000001",
"data": {
"attributes": {
"displayName": "Johnny",
"favoriteSports": [
"Football",
"Basketball"
]
},
"preferredLanguages": [
"en",
"fr"
]
},
"id": "00000000-0000-0002-0000-000000000000",
"insertInstant": 1446064706250,
"lastLoginInstant": 1456064601291,
"roles": [
"user",
"community_helper"
],
"username": "johnny123",
"usernameStatus": "ACTIVE"
}
],
"timezone": "America/Denver",
"twoFactorEnabled": false,
"usernameStatus": "ACTIVE",
"username": "johnny123",
"verified": true
}
]
}
10. Verify a User’s Email
This API is used to mark a User’s email as verified. This is usually called after the User receives the verification email after they register and they click the link in the email.
10.1. Request
Verifies the User’s email address using the verificationId
.
POST /api/user/verify-email/{verificationId}
verificationId [String] Required |
The verification Id generated by Passport used to verify the User’s account is valid by ensuring they have access to the provided email address. |
10.2. Response
The response does not contain a body. It only contains one of the status codes below.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
404 |
The object you are trying to updated doesn’t exist. The response will be empty. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
11. Resend Verification Email
This API is used to resend the verification email to a User. This API is useful if the User has deleted the email, or the verification Id has expired. By default, the verification Id will expire after 24 hours.
11.1. Request
PUT /api/user/verify-email?email={email}
email [String] Required |
The email address used to uniquely identify the User. |
Resend the verification email using an API key
PUT /api/user/verify-email?email={email}&sendVerifyEmail={sendVerifyEmail}
email [String] Required |
The email address used to uniquely identify the User. |
sendVerifyEmail [Boolean] Optional defaults to |
If you would only like to generate a new This may be useful if you need to integrate the Email Verification process using a third party messaging service. |
11.2. Response
When authenticated using an API key a response body will be provided. If an API key was not used to authenticate the request no body is returned.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body if an API key was used for authentication. If no API key was provided no response body will be returned. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
403 |
The verify email functionality has been disabled. Passport is unable to send Email Verification emails. |
404 |
The object you are trying to updated doesn’t exist. The response will be empty. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |
verificationId [String] Available Since 1.16.0 |
The email verification Id that was generated by this API request. This identifier may be used by the Verify a User’s Email API. This field is only returned in the JSON response body if the request was authenticated using an API key, if an API key is not used no response body is returned. |
{
"verificationId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}
12. Start Forgot Password Workflow
This API is used to start the forgot password workflow for a single User.
For example, on your login form you may have a button for Forgot your password. This would be the API you would call to initiate the request for the user. If the email configuration is complete, the user
will be sent the forgot password email containing a link containing the changePasswordId
. The provided link should take the user to a form that allows them to change their password. This form should contain a hidden
field for the changePasswordId
generated by this API.
By default the changePasswordId
is valid to be used with the Change Password API for 10 minutes. If a 404
is returned when using this Id to change the password, the workflow
will need to be started again to generate a new identifier. This duration can be modified using the System Configuration API or in the Passport UI.
You may optionally authenticate this request with an API key to allow for some additional request parameters and the generated changePasswordId
will be returned in the JSON body.
This may be helpful if you wish to use your own email system or you have an alternative method to call the Change Password API.
12.1. Request
Start the forgot password workflow without an API Key.
POST /api/user/forgot-password
Available Since Version 1.16.0 |
loginId [String] Required |
The login identifier of the user. The login identifier can be either the |
{
"loginId": "example@inversoft.com"
}
Start the forgot password workflow using an API key
POST /api/user/forgot-password
changePasswordId [String] Optional Available Since 1.16.0 |
The optional change password Id to be used on the Change a User’s Password API. It is recommended to omit this parameter and allow Passport to generate the identifier. Use this parameter only if you must supply your own value for integration into existing systems. |
email [String] Optional Deprecated |
The email address of the User. You must specify either email or username for the User. Once available, use |
loginId [String] Required Available Since 1.5.2 |
The login identifier of the user. The login identifier can be either the |
sendForgotPasswordEmail [Boolean] Optional defaults to |
Whether or not calling this API should attempt to send the user an email using the Forgot Password Email Template. Setting this to
false will skip the email attempt and only set the |
username [String] Optional Deprecated |
The username of the User. You must specify either email or username for the User. The username is not case sensitive. Once
available, use |
{
"changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4",
"loginId": "example@inversoft.com",
"sendForgotPasswordEmail": false
}
12.2. Response
Code | Description |
---|---|
200 |
The request was successful. Starting in version |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. Contact sales@inversoft.com for assistance. |
403 |
The forgot password functionality has been disabled. This is caused by an administrator setting the Forgot Password Email Template to the option Feature Disabled under Settings → System in Passport Backend. |
404 |
The User could not be found. |
422 |
The User does not have an email address, this request cannot be completed. Before attempting the request again add an email address to the user or if this is a child User that does not have an email address set the |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. |
changePasswordId [String] Available Since 1.5.2 |
The change password Id that was generated by this API request. This identifier may be used by the Change Password API. This field is only returned in the JSON response body if the request was authenticated using an API key, if an API key is not used no response body is returned. |
{
"changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}
13. Change a User’s Password
This API is used to change the User’s password.
This API may be used as the second part of the Forgot Password workflow. For example, after the User is sent an email that contains a link to
a web form that allows them to update their password you will call this API with the changePasswordId
and their updated password. If the
changePasswordId
is valid then the User’s password will be updated.
This API may also be used separately from the Forgot Password workflow by omitting the changePasswordId
and using the loginId
instead.
By default the changePasswordId
is valid for 10 minutes after it was generated. If a 404
is returned when using the change password Id,
the workflow will need to be started again to generate a new identifier. This duration can be modified using the System Configuration API or in the Passport UI.
13.1. Request
Changes a User’s password using the change password Id.
POST /api/user/change-password/{changePasswordId}
Available Since Version 1.16.0 |
changePasswordId [String] Required |
The
Available Since 1.21.1
If this |
currentPassword [String] Optional |
The User’s current password. When this parameter is provided the current password will be verified to be correct. |
password [String] Required |
The User’s new password. |
Changes a User’s password using a login Id or change password Id
POST /api/user/change-password/{changePasswordId}
changePasswordId [String] Optional |
The
When this value is provided it should be in place of the
Available Since 1.21.1
If this |
currentPassword [String] Optional Available Since 1.9.1 |
The User’s current password. When this parameter is provided the current password will be verified to be correct. |
loginId [String] Optional Available Since 1.9.2 |
The login identifier of the user. The login identifier can be either the
When this value is provided it should be in place of the |
password [String] Required |
The User’s new password. |
{
"currentPassword": "too many secrets",
"password": "Setec Astronomy"
}
13.2. Response
The response does not contain a body. It only contains one of the status codes below.
Code | Description |
---|---|
200 |
The request was successful. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. Contact sales@inversoft.com for assistance. |
404 |
The User could not be found using the |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. |
14. Flush the Search Engine
This API is used to issue a flush request to the Passport Search Engine. This will cause any cached data to be written to disk. In practice it is unlikely you’ll find a need for this API in production unless you are performing search requests immediately following an operation that modifies the index and expecting to see the results immediately.
14.1. Request
PUT /api/user/search
14.2. Response
The response does not contain a body. It only contains one of the status codes below.
Code | Description |
---|---|
200 |
The request was successful. The response will contain a JSON body. |
400 |
The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. |
401 |
You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
402 |
Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance. |
500 |
There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty. |