The import users operation gives privileged applications the ability to create a new user and set the user’s password. The password
attribute in this operation uses the same format for specifying passwords as the set password request, allowing both cleartext and pre-encoded password values. See Password encoding for our supported encodings for passwords.
The POST /environments/{{envID}}/users
operation imports a new user resource to the specified environment. This operation uses the application/vnd.pingidentity.user.import+json
custom content type in the request header.
New users must be assigned to a population
resource identified by its ID, and the request must set a value for the username
attribute. In addition, this operation supports the password
attribute, which can accept a pre-encoded password value and a forceChange
value of false.
The username
attribute must be unique to an environment (spanning populations). Access to populations is determined by roles. It’s possible that username
conflicts may arise, if you or your worker application attempt to create a user that exists in a population to which you have no access.
You can set a read-only emailVerified
flag to initiate the email verification workflow. This flag can be set to true
or false
for the Create User (Import) operation. For the Create User operation, the flag can only be set to false
. If a user’s emailVerified
flag is set to false
and they run the Verify User operation or Verify Email operation, the flag will be set to true
.
Optionally, you can set the lifecycle.status
property to VERIFICATION_REQUIRED
and the lifecycle.suppressVerificationCode
property to false
if you want the user to receive a verification email automatically. For this use case, you must provide a valid email
address for the imported user. The user’s verifyStatus
property is returned as NOT_INITIATED
and remains in that state until the user verifies the account.
New users who are authenticating using a social login (such as, Google or Facebook) must be assigned an identity provider with the identityProvider.id
attribute. The identityProvider.type
value is read-only, and its value is dependent on the value of identityProvider.id
. If identityProvider.id
is not provided, and you’re not authenticating using an external gateway, the default value of identityProvider.type
is PING_ONE
.
If you’re authenticating using an external gateway, the identityProvider.id
attribute must be null. See Gateway Management for more information about external gateways. When a user is imported you can add correlation attributes that will get sent as as the link attributes value. For example if you had correlationAttributes.customAttribute1 and you set the link attribute to customAttribute1, the value in the correlationAttributes is used to identify the user in the remote directory.
If successful, the response returns a 201 Successfully created
message and shows the new user resource’s property data.
See Users and User Operations for important overview information.
Create a population to get a popID
. See Create Population. Run Read All Populations to find an existing population.
Property | Type | Required? |
---|---|---|
email |
String | Optional |
name.given |
String | Optional |
name.family |
String | Optional |
population.id |
String | Optional |
lifecycle.status |
String | Optional |
lifecycle.suppressVerificationCode |
Boolean | Optional |
username |
String | Required |
password.value |
String | Optional |
password.forceChange |
Boolean | Optional |
See the User operations data model for full property descriptions.