post:
  operationId: setIdentityPassword
  tags:
    - Password Management
  summary: Set Identity's Password
  description: |
    This API is used to set a password for an identity. 
    
    An identity can change their own password (as well as any of their accounts' passwords) if they use a token generated by their IDN user, such as a [personal access token](https://developer.sailpoint.com/idn/api/authentication#personal-access-tokens) or ["authorization_code" derived OAuth token](https://developer.sailpoint.com/idn/api/authentication#authorization-code-grant-flow).
    
    A token with [API authority](https://developer.sailpoint.com/idn/api/authentication#client-credentials-grant-flow) can be used to change **any** identity's password or the password of any of the identity's accounts. 
    "API authority" refers to a token that only has the "client_credentials" grant type.

    You can use this endpoint to generate an `encryptedPassword` (RSA encrypted using publicKey). 
    To do so, follow these steps:

    1. Use [Query Password Info](https://developer.sailpoint.com/idn/api/v3/query-password-info) to get the following information: `identityId`, `sourceId`, `publicKeyId`, `publicKey`, `accounts`, and `policies`. 

    2. Choose an account from the previous response that you will provide as an `accountId` in your request to set an encrypted password. 

    3. Use [Set Identity's Password](https://developer.sailpoint.com/idn/api/v3/set-password) and provide the information you got from your earlier query. Then add this code to your request to get the encrypted password:

    ```java
    import javax.crypto.Cipher;
    import java.security.KeyFactory;
    import java.security.PublicKey;
    import java.security.spec.X509EncodedKeySpec;
    import java util.Base64;

    String encrypt(String publicKey, String toEncrypt) throws Exception {
      byte[] publicKeyBytes = Base64.getDecoder().decode(publicKey);
      byte[] encryptedBytes = encryptRsa(publicKeyBytes, toEncrypt.getBytes("UTF-8"));
      return Base64.getEncoder().encodeToString(encryptedBytes);
    }

    private byte[] encryptRsa(byte[] publicKeyBytes, byte[] toEncryptBytes) throws Exception {
      PublicKey key = KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(publicKeyBytes));
      String transformation = "RSA/ECB/PKCS1Padding";
      Cipher cipher = Cipher.getInstance(transformation);
      cipher.init(1, key);
      return cipher.doFinal(toEncryptBytes);
    }
    ```    
    
    In this example, `toEncrypt` refers to the plain text password you are setting and then encrypting, and the `publicKey` refers to the publicKey you got from the first request you sent. 

    You can then use [Get Password Change Request Status](https://developer.sailpoint.com/idn/api/v3/get-password-change-status) to check the password change request status. To do so, you must provide the `requestId` from your earlier request to set the password. 
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '../schemas/PasswordChangeRequest.yaml'
        example: {
          "identityId": "8a807d4c73c545510173c545f0a002ff",
          "encryptedPassword": "GIAP7TaAg7Y2EJtFojokBDvHQ/iXF3qk0z0+eLusqXMSkEhAfr34GydFLy+BM2uZB94cwbTYKi9rRrCRRdh8610VeqpRDjhuc28nOPYqTJOx09IGJdr8dl4mbhC1f21JCqMBBrFSA4VQQvd6OMVsceoXTjDI0aKahRYNjlMlsOuaIUZeNQxWBydLuR6vYG3qAKEPCzYZbvyYuBUylUWArfqwV4dgwKGDgDkTLBkQU9LVu3rssc+BXaex6l6JcBDiPg7wvKD1G3lZ+BaGrMknbx3j0T2Uivg+HxwTf7PmtAua6O9M7F984c79KM+sYFTU37MAdlWZu/cy+w2DdHVdCg==",
          "publicKeyId": "YWQ2NjQ4MTItZjY0NC00MWExLWFjMjktOGNmMzU3Y2VlNjk2",
          "accountId": "CN=Abby Smith,OU=Austin,OU=Americas,OU=Demo,DC=seri,DC=acme,DC=com",
          "sourceId": "8a807d4c73c545510173c545d4b60246"
        }
  responses:
    '202':
      description: Reference to the password change.
      content:
        application/json:
          schema:
            $ref: '../schemas/PasswordChangeResponse.yaml'
          examples:
            Password change is in progress:
              value:
                {
                  "state": "IN_PROGRESS",
                  "requestId": "089899f13a8f4da7824996191587bab9",
                }
    '400':
      $ref: '../../v3/responses/400.yaml'
    '401':
      $ref: '../../v3/responses/401.yaml'
    '403':
      $ref: '../../v3/responses/403.yaml'
    '429':
      $ref: '../../v3/responses/429.yaml'
    '500':
      $ref: '../../v3/responses/500.yaml'