Okta Password API

openapi: 3.2.0
info:
  title: MyAccount Management Password API
  version: 2025.01.1
  description: 'APIs for managing a user''s own emails, phones, profile, and app authenticators.

    > **Note:** The MyAccount API doesn''t support delegated authentication.'
  termsOfService: https://developer.okta.com/terms/
  contact:
    name: Okta Developer Team
    url: https://developer.okta.com/
    email: devex-public@okta.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: logo.svg
    backgroundColor: transparent
    altText: Okta Developer
servers:
- url: https://{yourOktaDomain}
  variables:
    yourOktaDomain:
      default: subdomain.okta.com
      description: The domain of your organization. This can be an official Okta domain (for example, `okta.com` or `oktapreview.com`) or one of your configured custom domains.
tags:
- name: Password
  description: 'The MyAccount Password API provides operations to enroll, update, and delete passwords.


    > **Note:** Super admins can enable the IDP MyAccount API password feature. See Enable self-service features.


    ### API versioning

    A valid API version in the `Accept` header is required to access the API. Current version: `1.0.0`

    ```json

    Accept: application/json; okta-version=1.0.0

    ```'
paths:
  /idp/myaccount/password:
    get:
      summary: Retrieve a Password
      description: 'Retrieves the current user''s password status

        > **Note:** This request only returns information about the password, not the password itself.'
      operationId: getPassword
      responses:
        '200':
          $ref: '#/components/responses/Password-Enrolled-Response'
        '401':
          $ref: '#/components/responses/Error-IdpMyAccountNotEnabled-Response-401'
      security:
      - oauth2:
        - okta.myAccount.password.read
      tags:
      - Password
      x-okta-lifecycle:
        lifecycle: GA
        isGenerallyAvailable: true
    post:
      summary: Create a Password
      description: Creates and enrolls a password for the current user
      operationId: createPassword
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  type: object
                  description: Defines the password on the profile
                  required:
                  - password
                  properties:
                    password:
                      type: string
                      example: Abcd12345
                      writeOnly: true
              required:
              - profile
            examples:
              New-Password:
                value:
                  profile:
                    password: Abcd1234
        description: New password
      responses:
        '201':
          $ref: '#/components/responses/Password-Enrolled-Response'
        '400':
          $ref: '#/components/responses/Error-InvalidPassword-Reponse-400'
        '401':
          $ref: '#/components/responses/Error-IdpMyAccountNotEnabled-Response-401'
        '403':
          $ref: '#/components/responses/Error-PasswordConflict-Response-409'
      security:
      - oauth2:
        - okta.myAccount.password.manage
      tags:
      - Password
      x-okta-lifecycle:
        lifecycle: GA
        isGenerallyAvailable: true
    put:
      summary: Replace a Password
      description: Replaces the password for the current user
      operationId: replacePassword
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  type: object
                  description: Defines the password on the profile
                  required:
                  - password
                  properties:
                    password:
                      type: string
                      example: Abcd12345
                      writeOnly: true
              required:
              - profile
            examples:
              New-Password:
                value:
                  profile:
                    password: Abcd1234
        description: New password
      responses:
        '201':
          $ref: '#/components/responses/Password-Enrolled-Response'
        '400':
          $ref: '#/components/responses/Error-InvalidPassword-Reponse-400'
        '401':
          $ref: '#/components/responses/Error-IdpMyAccountNotEnabled-Response-401'
        '403':
          $ref: '#/components/responses/Error-Email-Response-403'
      security:
      - oauth2:
        - okta.myAccount.password.manage
      tags:
      - Password
      x-okta-lifecycle:
        lifecycle: GA
        isGenerallyAvailable: true
    delete:
      summary: Delete a Password
      description: Deletes the current user's enrolled password
      operationId: deletePassword
      responses:
        '204':
          description: No Content
          content:
            application/json;okta-version=1.0.0: {}
        '401':
          $ref: '#/components/responses/Error-IdpMyAccountNotEnabled-Response-401'
        '404':
          $ref: '#/components/responses/Error-PasswordResourceNotFound-Response-404'
      security:
      - oauth2:
        - okta.myAccount.password.manage
      tags:
      - Password
      x-okta-lifecycle:
        lifecycle: GA
        isGenerallyAvailable: true
components:
  responses:
    Error-IdpMyAccountNotEnabled-Response-401:
      description: Unauthorized
      content:
        application/json;okta-version=1.0.0:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            IDP-MyAccount-not-enabled-401:
              value:
                errorCode: E0000015
                errorSummary: You do not have permission to access the feature you are requesting
                errorLink: E0000015
                errorId: oaeStOuPPxDRUm3PJhf-tL7bQ
                errorCauses: []
    Error-Email-Response-403:
      description: Forbidden
      content:
        application/json;okta-version=1.0.0:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Secondary-Email:
              value:
                errorCode: E0000038
                errorSummary: This operation is not allowed in the user's current status.
                errorLink: E0000038
                errorId: oaejUwz8U5FQ_SyggQwz1kC3w
                errorCauses:
                - errorSummary: Secondary email is not enabled as an authenticator for your org.
    Error-PasswordConflict-Response-409:
      description: Conflict
      content:
        application/json;okta-version=1.0.0:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Password-Conflict-409:
              value:
                errorCode: E0000157
                errorSummary: This account already has a password set as an authenticator.
                errorLink: E0000157
                errorId: oaejUwz8U5FQ_SyggQwz1kC3w
                errorCauses:
                - errorSummary: This account already has a password set as an authenticator.
    Password-Enrolled-Response:
      description: Example response
      content:
        application/json;okta-version=1.0.0:
          schema:
            $ref: '#/components/schemas/PasswordResponse'
          examples:
            Success-Response:
              value:
                id: 00T196qTp3LIMZQ0L0g3
                status: ACTIVE
                created: '2020-01-14T20:05:32.000Z'
                lastUpdated: '2020-01-14T20:05:32.000Z'
                _links:
                  self:
                    href: https://example.okta.com/idp/myaccount/password
                    hints:
                      allow:
                      - GET
                      - DELETE
                      - PUT
    Error-PasswordResourceNotFound-Response-404:
      description: Not Found
      content:
        application/json;okta-version=1.0.0:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Password-Resource-Not-Found-404:
              value:
                errorCode: E0000007
                errorSummary: 'Not found: Resource not found: 796bc844c1802c5ad5a65e1dbd26c30a (UserProfilePassword)'
                errorLink: E0000007
                errorId: oaejUwz8U5FQ_SyggQwz1kC3w
                errorCauses: []
    Error-InvalidPassword-Reponse-400:
      description: Bad Request
      content:
        application/json;okta-version=1.0.0:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Invalid-Password-400:
              value:
                errorCode: E0000001
                errorSummary: 'Api validation failed: Password'
                errorLink: E0000001
                errorId: oaejUwz8U5FQ_SyggQwz1kC3w
                errorCauses:
                - errorSummary: Invalid password.
  schemas:
    Error:
      description: Standard API error object
      type: object
      properties:
        errorCauses:
          type: array
          description: (Optional) Further information about what caused this error
          items:
            type: object
            properties:
              errorSummary:
                type: string
                description: A natural language explanation of the error
                example: Bad request because XYZ is missing.
                readOnly: true
        errorCode:
          type: string
          description: A code that is associated with this error type
          example: E0000001
          readOnly: true
        errorId:
          type: string
          description: A unique identifier for this error. This can be used by Okta Support to help with troubleshooting.
          example: oaeWGQKoQHeQmy0u8w8bPwi_Q
          readOnly: true
        errorLink:
          type: string
          description: A link to documentation with a more detailed explanation of the error (not yet implemented and is currently the same value as the 'errorCode')
          example: E0000001
          readOnly: true
        errorSummary:
          type: string
          description: A natural language explanation of the error
          example: Bad request because XYZ is missing.
          readOnly: true
    PasswordResponse:
      description: Password response object
      type: object
      properties:
        created:
          type: string
          description: If password is `ACTIVE`, returns the date when password was first enrolled
        id:
          type: string
          minLength: 1
          readOnly: true
        lastUpdated:
          type: string
          description: If password is `ACTIVE`, returns the date when password was last updated
        status:
          type: string
          description: '`ACTIVE`, `EXPIRED`, `SUSPENDED`, `NOT_ENROLLED`'
        _links:
          type: object
          description: Discoverable resources related to the password
          properties:
            self:
              type: object
              description: Link to the resource (self)
              properties:
                href:
                  type: string
                  description: Link URI
                  minLength: 1
                hints:
                  type: object
                  description: Describes the allowed HTTP verbs for the `href`
                  properties:
                    allow:
                      type: array
                      items:
                        type: string
                        enum:
                        - DELETE
                        - GET
                        - PUT
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Pass the access_token as the value of the Authorization header: `Authorization: Bearer {access_token}`'
      flows:
        authorizationCode:
          authorizationUrl: /oauth2/v1/authorize
          tokenUrl: /oauth2/v1/token
          scopes:
            okta.myAccount.appAuthenticator.maintenance.manage: Write access to non-sensitive attributes of user app authenticator enrollments
            okta.myAccount.appAuthenticator.maintenance.read: Read access to non-sensitive attributes of user app authenticator enrollments
            okta.myAccount.appAuthenticator.manage: Write access to user app authenticator enrollments
            okta.myAccount.appAuthenticator.read: Read access to user app authenticator enrollments
            okta.myAccount.authenticators.manage: Write access to user authenticator enrollments
            okta.myAccount.authenticators.read: Read access to user authenticator configurations and enrollments
            okta.myAccount.email.manage: Write access to user emails
            okta.myAccount.email.read: Read access to user emails
            okta.myAccount.oktaApplications.read: Read access to the Okta apps list
            okta.myAccount.organization.read: Read access to org details
            okta.myAccount.password.manage: Write access to user password
            okta.myAccount.password.read: Read access to user password metadata
            okta.myAccount.phone.manage: Write access to user phones
            okta.myAccount.phone.read: Read access to user phones
            okta.myAccount.profile.manage: Write access to user profile and schema
            okta.myAccount.profile.read: Read access to user profile and schema
            okta.myAccount.sessions.manage: Write access to user sessions
externalDocs:
  description: Find more info here
  url: https://developer.okta.com