API ReferenceManagementUsers
POST
/v1/mgmt/user/create/batch

Authorization

Descope Project ID and Management Key
AuthorizationBearer <token>

Project ID:Management Key as bearer token.

In: header

Request Body

application/json

users?array<CreateUsers>
invite?boolean
sendMail?boolean
sendSMS?boolean
inviteUrl?string
templateOptions?object
locale?string

Batch Create Users, using a valid management key.

This API endpoint will batch create new users utilizing a valid management key.

This API endpoint allows you to configure all aspects of a user:

  • loginId
  • email
  • phone
  • verified settings (phone, email) - one must be set to true
  • displayName
  • roleNames
  • Tenant configurations - which tenantIds, which roleNames. The userTenants can include multiple items Ex:
"userTenants": [
{
  "tenantId": "T2IMjmRfYTQHlbaastz3im59ERS3",
  "roleNames": [
    "Test"
  ]
},
{
  "tenantId": "T2Igau6dX1R6SkomtFCdBLrc3r67",
  "roleNames": [
    "Test"
  ]
}

Additionally, you can create a user with multiple login IDs by passing an array of loginIds in string format within the additionalIdentifiers key.

You can also decide whether to invite the users, configure the inviteUrl, and whether to send invites via email or SMS.

When importing with hashed passwords, see this guide for further detailed configuration of password hash formats.

Next Steps

Once the user is created, the user can then login utilizing any sign-in api supported. This will then switch the user from invited to active.

See also

curl -X POST "https://api.descope.com/v1/mgmt/user/create/batch" \  -H "Content-Type: application/json" \  -d '{}'
{  "createdUsers": [    {      "loginIds": [        "string"      ],      "userId": "string",      "name": "string",      "email": "string",      "phone": "string",      "verifiedEmail": true,      "verifiedPhone": true,      "roleNames": [        "string"      ],      "userTenants": [        {          "tenantId": "string",          "roleNames": [            "string"          ],          "tenantName": "string",          "permissions": [            "string"          ],          "roleIds": [            "string"          ]        }      ],      "status": "string",      "externalIds": [        "string"      ],      "picture": "string",      "test": false,      "customAttributes": {        "attribute-key": "attribute-value"      },      "createdTime": 0,      "TOTP": false,      "SAML": false,      "OAuth": {        "property1": false,        "property2": false      },      "webauthn": true,      "password": true,      "ssoAppIds": [        "string"      ],      "givenName": "string",      "middleName": "string",      "familyName": "string",      "editable": true,      "SCIM": true,      "push": true,      "permissions": [        "string"      ],      "OIDC": true,      "consentExpiration": 0,      "recoveryEmail": "string",      "verifiedRecoveryEmail": true,      "recoveryPhone": "string",      "verifiedRecoveryPhone": true,      "modifiedTime": 0,      "roleIds": [        "string"      ],      "recoveryCodes": true    }  ],  "failedUsers": [    {      "failure": "string",      "user": {        "loginIds": [          "string"        ],        "userId": "string",        "name": "string",        "email": "string",        "phone": "string",        "verifiedEmail": true,        "verifiedPhone": true,        "roleNames": [          "string"        ],        "userTenants": [          {            "tenantId": "string",            "roleNames": [              "string"            ],            "tenantName": "string",            "permissions": [              "string"            ],            "roleIds": [              "string"            ]          }        ],        "status": "string",        "externalIds": [          "string"        ],        "picture": "string",        "test": false,        "customAttributes": {          "attribute-key": "attribute-value"        },        "createdTime": 0,        "TOTP": false,        "SAML": false,        "OAuth": {          "property1": false,          "property2": false        },        "webauthn": true,        "password": true,        "ssoAppIds": [          "string"        ],        "givenName": "string",        "middleName": "string",        "familyName": "string",        "editable": true,        "SCIM": true,        "push": true,        "permissions": [          "string"        ],        "OIDC": true,        "consentExpiration": 0,        "recoveryEmail": "string",        "verifiedRecoveryEmail": true,        "recoveryPhone": "string",        "verifiedRecoveryPhone": true,        "modifiedTime": 0,        "roleIds": [          "string"        ],        "recoveryCodes": true      }    }  ],  "additionalErrors": {    "property1": "string",    "property2": "string"  }}
export interface Response {createdUsers?: {loginIds?: string[]userId?: stringname?: stringemail?: stringphone?: stringverifiedEmail?: booleanverifiedPhone?: booleanroleNames?: string[]userTenants?: UserTenants[]status?: stringexternalIds?: string[]picture?: stringtest?: boolean/** * Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays. */customAttributes?: {[k: string]: string}createdTime?: numberTOTP?: booleanSAML?: booleanOAuth?: {[k: string]: boolean}webauthn?: booleanpassword?: booleanssoAppIds?: string[]givenName?: stringmiddleName?: stringfamilyName?: stringeditable?: booleanSCIM?: booleanpush?: booleanpermissions?: string[]OIDC?: booleanconsentExpiration?: numberrecoveryEmail?: stringverifiedRecoveryEmail?: booleanrecoveryPhone?: stringverifiedRecoveryPhone?: booleanmodifiedTime?: number/** * roleIds holds the IDs of this entry's roles. Order is NOT guaranteed to match *  roleNames — do not pair them by index. Use roleIds or roleNames independently. */roleIds?: string[]/** * whether the user has set up recovery codes */recoveryCodes?: boolean}[]failedUsers?: CreateUsersFailureResponse[]additionalErrors?: {[k: string]: string}}export interface UserTenants {tenantId?: stringroleNames?: string[]tenantName?: stringpermissions?: string[]/** * roleIds holds the IDs of this entry's roles. Order is NOT guaranteed to match *  roleNames — do not pair them by index. Use roleIds or roleNames independently. */roleIds?: string[]}export interface CreateUsersFailureResponse {failure?: stringuser?: {loginIds?: string[]userId?: stringname?: stringemail?: stringphone?: stringverifiedEmail?: booleanverifiedPhone?: booleanroleNames?: string[]userTenants?: UserTenants[]status?: stringexternalIds?: string[]picture?: stringtest?: boolean/** * Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays. */customAttributes?: {[k: string]: string}createdTime?: numberTOTP?: booleanSAML?: booleanOAuth?: {[k: string]: boolean}webauthn?: booleanpassword?: booleanssoAppIds?: string[]givenName?: stringmiddleName?: stringfamilyName?: stringeditable?: booleanSCIM?: booleanpush?: booleanpermissions?: string[]OIDC?: booleanconsentExpiration?: numberrecoveryEmail?: stringverifiedRecoveryEmail?: booleanrecoveryPhone?: stringverifiedRecoveryPhone?: booleanmodifiedTime?: number/** * roleIds holds the IDs of this entry's roles. Order is NOT guaranteed to match *  roleNames — do not pair them by index. Use roleIds or roleNames independently. */roleIds?: string[]/** * whether the user has set up recovery codes */recoveryCodes?: boolean}}
Was this helpful?

Create User POST

### Create a new user, using a valid management key. This API endpoint will create a new user utilizing a valid management key. This API endpoint allows you to configure all aspects of a user: - loginId - email - phone - verified settings (phone, email) - one must be set to true - displayName - roleNames - Tenant configurations - which tenantIds, which roleNames. The userTenants can include multiple items Ex: ``` "userTenants": [ { "tenantId": "T2IMjmRfYTQHlbaastz3im59ERS3", "roleNames": [ "Test" ] }, { "tenantId": "T2Igau6dX1R6SkomtFCdBLrc3r67", "roleNames": [ "Test" ] } ``` Additionally, you can create a user with multiple login IDs by passing an array of loginIds in string format within the `additionalIdentifiers` key. ### Next Steps Once the user is created, the user can then login utilizing any sign-in api supported. This will then switch the user from invited to active. ### See also - See [Manage User](/manage/users) for further details on managing users. - See [The User Object](/api/overview#the-user-object) for further details on the user object.

Patch User PATCH

### Patch a user's details, using a valid management key. This API endpoint will patch a user's details of a user utilizing a valid management key. Additionally, you can patch a user with multiple login IDs by passing an array of loginIds in string format within the `additionalIdentifiers` key. This allows you to add additional login identifiers to an existing user without performing a full user update. <Callout title="Important" type="warn"> When adding additional identifiers to a user who has an SSO login ID, the user may be able to authenticate outside of SSO whenever SSO is not enforced and non-SSO methods (such as magic link or password) are available. See [Risks in Merging SSO and Non-SSO Identities](/sso/merging-sso-identities-risk) before using this field on SSO users. </Callout> ### See also - See [Manage Users](/manage/users) for further details on managing users. - See [The User Object](/api/overview#the-user-object) for further details on the user object.