Elastic Path Password Profiles API

openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26 19:10:23+00:00
  title: Addresses Introduction Account Addresses Password Profiles API
  description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.


    You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- BearerToken: []
tags:
- name: Password Profiles
  description: 'A `password_profile` resource represents a specific configuration that allows users to authenticate through username and password.


    Password Profiles support One-Time Password Tokens, which can be used to use passwordless login or password reset.


    An authentication realm can have multiple Password Profiles. You can use this flexibility in many ways. For instance, if you want to migrate an existing pool of users from another system with their own usernames and passwords, they can use one profile, while the rest of the users use another.


    Another use case is enabling shopper impersonation, where shoppers can authenticate using their own username and password in one profile. Meanwhile, admins can have a different username and password for the same user in a separate profile, shown as the "Impersonation Profile". This process can be automated using a Backend-For-Frontend (BFE) or One-Time Password Tokens. In the example shown below, both John and Joan can log in with their credentials, and an admin can also log in as Joan using the "Impersonation Profile".


    ![password profiles](/assets/password-profiles.png)

    '
paths:
  /v2/authentication-realms/{realmId}/password-profiles:
    get:
      tags:
      - Password Profiles
      summary: Get Password Profiles
      description: Retrieve password profiles for the specified authentication realm.
      operationId: get-v2-authentication-realms-realmId-password-profiles
      parameters:
      - name: realmId
        in: path
        description: The ID of the authentication realm.
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/page-limit'
      - $ref: '#/components/parameters/page-offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PasswordProfileResponse'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                list_password_profiles:
                  summary: List of password profiles
                  value:
                    data:
                    - id: a2f6d4c0-1d2b-4b3a-9e5a-2f4b1c7d8e9f
                      type: password_profile
                      name: Default Passwords
                      require_uppercase: true
                      require_numbers: true
                      min_length: 10
                    - id: b3e7f5a1-2c3d-4e4b-8f6a-3e5c2d8f9a0b
                      type: password_profile
                      name: Impersonation Profile
                      require_uppercase: false
                      require_numbers: false
                      min_length: 8
                    meta:
                      results:
                        total: 2
                      page:
                        limit: 25
                        offset: 0
                    links:
                      current: https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/password-profiles?page%5Boffset%5D=0&page%5Blimit%5D=25
                      first: https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/password-profiles?page%5Boffset%5D=0&page%5Blimit%5D=25
                      last: null
                      next: null
                      prev: null
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Password Profiles
      summary: Create Password Profile
      description: Create a password profile for the specified authentication realm.
      operationId: post-v2-authentication-realms-realmId-password-profiles
      parameters:
      - name: realmId
        in: path
        description: The ID of the authentication realm.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/PasswordProfile'
              required:
              - data
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PasswordProfileResponse'
                  links:
                    $ref: '#/components/schemas/SelfLink'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/authentication-realms/{realmId}/password-profiles/{profileId}:
    get:
      tags:
      - Password Profiles
      summary: Get Password Profile
      description: Retrieve a specific password profile by ID.
      operationId: get-v2-authentication-realms-realmId-password-profiles-profileId
      parameters:
      - name: realmId
        in: path
        description: The ID of the authentication realm.
        required: true
        schema:
          type: string
          format: uuid
      - name: profileId
        in: path
        description: The ID of the password profile.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PasswordProfileResponse'
                  links:
                    $ref: '#/components/schemas/SelfLink'
              examples:
                get_password_profile:
                  summary: Password profile
                  value:
                    data:
                      id: a2f6d4c0-1d2b-4b3a-9e5a-2f4b1c7d8e9f
                      type: password_profile
                      name: Default Passwords
                    links:
                      self: https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/password-profiles/a2f6d4c0-1d2b-4b3a-9e5a-2f4b1c7d8e9f
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Password Profiles
      summary: Update Password Profile
      description: Update a specific password profile by ID.
      operationId: put-v2-authentication-realms-realmId-password-profiles-profileId
      parameters:
      - name: realmId
        in: path
        description: The ID of the authentication realm.
        required: true
        schema:
          type: string
          format: uuid
      - name: profileId
        in: path
        description: The ID of the password profile.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/PasswordProfile'
              required:
              - data
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PasswordProfileResponse'
                  links:
                    $ref: '#/components/schemas/SelfLink'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Password Profiles
      summary: Delete Password Profile
      description: Delete a specific password profile by ID.
      operationId: delete-v2-authentication-realms-realmId-password-profiles-profileId
      parameters:
      - name: realmId
        in: path
        description: The ID of the authentication realm.
        required: true
        schema:
          type: string
          format: uuid
      - name: profileId
        in: path
        description: The ID of the password profile.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/authentication-realms/{realmId}/password-profiles/{profileId}/one-time-password-token-request:
    post:
      tags:
      - Password Profiles
      summary: Create One-Time Password Token Request
      description: Create a one-time password token request for the specified password profile.
      operationId: post-v2-authentication-realms-realmId-password-profiles-profileId-one-time-password-token-request
      parameters:
      - name: realmId
        in: path
        description: The ID of the authentication realm.
        required: true
        schema:
          type: string
          format: uuid
      - name: profileId
        in: path
        description: The ID of the password profile.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/OneTimePasswordTokenRequestInput'
              required:
              - data
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OneTimePasswordTokenRequestResponse'
        '202':
          description: Accepted
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PasswordProfile:
      type: object
      properties:
        type:
          type: string
          description: Specifies the type of object. Set this value to `password_profile`.
          const: password_profile
        name:
          type: string
          description: Specifies the name of the password profile.
          example: my-password-profile
        username_format:
          type: string
          description: The format the `username` field must be in when creating or updating a [User Authentication Password Profile Info](/docs/api/single-sign-on/post-v-2-authentication-realms-realm-id-user-authentication-info-user-auth-info-id-user-authentication-password-profile-info). You can change the `username_format` setting, however, the changes apply only to the users created or updated after changing this setting. The new setting does not change the `username_format` for existing users.
          enum:
          - email
          - any
          x-enumDescriptions:
            email: The `username` must be a valid e-mail.
            any: The `username` can be any string.
          example: email
        enable_one_time_password_token:
          type: boolean
          description: This enables one time password token requests and events for authentication. This feature is disabled by default.
          example: true
      required:
      - type
      - name
    MetaTimestamps:
      type: object
      properties:
        created_at:
          description: The date the resource is created.
          type: string
          format: date-time
          example: '2021-02-23T09:40:33.882Z'
        updated_at:
          description: The date the resource is updated.
          type: string
          format: date-time
          example: '2021-02-23T09:40:33.882Z'
    OneTimePasswordTokenRequestResponse:
      allOf:
      - $ref: '#/components/schemas/OneTimePasswordTokenRequestInput'
      - type: object
        properties:
          id:
            type: string
            format: uuid
            description: The unique identifier for the one-time password token request.
            example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          token:
            type: string
            description: The generated one-time password token.
            example: '123456'
          expires_at:
            type: string
            format: date-time
            description: The expiration time of the token.
            example: '2023-12-01T10:30:00Z'
          meta:
            $ref: '#/components/schemas/MetaTimestamps'
    OneTimePasswordTokenRequestInput:
      type: object
      properties:
        type:
          const: one-time-password-token-request
        purpose:
          type: string
          description: An information field indicating why the user submitted this request. Your [integration](/docs/api/integrations/integrations-introduction) can inspect this field and can change subsequent processing.
          enum:
          - reset_password
          - passwordless_authentication
          x-enumDescriptions:
            reset_password: This request is because the user does not known their password.
            passwordless_authentication: This request is because the user wants to authenticate with passwordless authentication
          example: password_reset
        username:
          type: string
          description: The username for the token request.
          example: user@example.com
      required:
      - type
      - purpose
      - username
    PasswordProfileResponse:
      allOf:
      - $ref: '#/components/schemas/PasswordProfile'
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/UUID'
            description: The unique identifier for a Password Profile.
          meta:
            $ref: '#/components/schemas/MetaTimestamps'
            description: Additional information for this password profile.
          links:
            type: object
            properties:
              self:
                description: A URL to the specific resource.
                type: string
                format: uri
                example: https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/password-profiles/abc123
    UUID:
      type: string
      description: The unique identifier.
      format: uuid
      example: deb6b25f-8451-4211-9a22-95610333df23
    PaginationLinks:
      type: object
      properties:
        current:
          type: string
          format: uri
          description: The current page of data.
        first:
          type:
          - string
          - 'null'
          format: uri
          description: The first page of data.
        last:
          type:
          - string
          - 'null'
          format: uri
          description: The last page of data.
        next:
          type:
          - string
          - 'null'
          format: uri
          description: The next page of data.
        prev:
          type:
          - string
          - 'null'
          format: uri
          description: The previous page of data.
        self:
          type: string
          format: uri
          description: The current resource URL.
    Error:
      type: object
      required:
      - status
      - title
      properties:
        title:
          type: string
          description: A brief summary of the error.
          examples:
          - Bad Request
        status:
          type: string
          format: string
          description: The HTTP response code of the error.
          examples:
          - '400'
        detail:
          type: string
          description: Optional additional detail about the error.
          examples:
          - The field 'name' is required
    SelfLink:
      type: object
      properties:
        self:
          description: A URL to the specific resource.
          type: string
          format: uri
    PaginationMeta:
      type: object
      properties:
        page:
          type: object
          properties:
            current:
              type: integer
              description: The current page number.
              example: 1
            limit:
              type: integer
              description: The number of items per page.
              example: 25
            offset:
              type: integer
              description: The number of items to offset by.
              example: 0
            total:
              type: integer
              description: The total number of pages.
              example: 1
        results:
          type: object
          properties:
            total:
              type: integer
              description: The total number of results after applying filters, if any, or all results.
              example: 1
    ErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        links:
          $ref: '#/components/schemas/SelfLink'
  parameters:
    page-limit:
      name: page[limit]
      in: query
      description: The number of records per page.
      required: false
      schema:
        type: integer
        format: int64
        minimum: 1
        maximum: 100
        default: 25
    page-offset:
      name: page[offset]
      in: query
      description: The number of records to offset the results by.
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
        default: 0
  responses:
    NotFoundError:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            not-found-error:
              value:
                errors:
                - title: Not Found
                  status: '404'
                  detail: Resource not found
    UnprocessableEntityError:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unprocessable-entity-error:
              value:
                errors:
                - title: Unprocessable Entity
                  status: '422'
                  detail: Constraint violation
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              summary: Internal server error
              value:
                errors:
                - title: Internal Server Error
                  status: '500'
                  detail: there was a problem processing your request
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            bad-request-error:
              value:
                errors:
                - title: Bad Request
                  status: '400'
                  detail: 'Validation failed: field ''Name'' on the ''min'' tag.'
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer