swagger: '2.0'
info:
  version: v1
  title: Credential API
  description: >-
    **Introduction to the Credential API**


    The Credential API is aimed at managing end users credentials, such as
    passwords, primary emails, etc. Credentials can be managed by the end user
    himself (Self Service) or via a 'Server-to-server' (Management / Admin) process.


    **Versions of the API**


    The current version of the credential API only manages the primary
    email addresses, primary phonenumbers and passwords. Subsequent versions will also support social accounts.


    **Explanations**


    What is a credential? In the context of identity management, the term
    credential can be informally defined as 'anything a user has that gives him
    access to his account'. A more subtle observation is that 'the term
    credential is used to denote both the thing uniquely possessed by the user
    and the corresponding information bound to the digital identity' (source: _A
    Taxonomy of User Authentication Methods_ - Gartner). iWelcome Credential API
    aims at managing the credential information that is linked to the digital
    identity.

    Email addresses (a.k.a. primary emails) can be considered as credential for
    2 reasons:
      * They may be used as identifier during login
      * Forgotten passwords can be reset using a link that is send to the user's email address.

    iWelcome calls an email address that is used for these purposes a _primary_
    email address.

    A (primary) phonenumber is a credential since it can be used to send a login-code for 2FA purposes.

host: www.iwelcome.com
schemes:
  - https
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/authorize'
    tokenUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/token'
    scopes:
      credential:primary-email:get: Allows the authenticated user to retrieve it's own primary email
      credential:primary-email:admin:get: Allows an admin to retrieve the primary email on behalf an user
      credential:primary-phonenumber:get: Allows the authenticated user to retrieve it's own primary phone number
      credential:primary-phonenumber:admin:get: Allows an admin to retrieve the primary phone number of another user
      credential:primary-email:post: Allows the authenticated user to request the operation for setting a new primary email and to confirm it's own email address
      credential:primary-email:admin:post: Allows an admin to request the operation for setting a new primary email on behalf of an user
      credential:primary-phonenumber:post: Allows the authenticated user to request the operation for setting a new primary phone number and to confirm the phone number using an otp
      credential:primary-phonenumber:admin:post: Allows an admin to request the operation for setting a new primary phone number and to confirm the phone by entering the otp on behalf of an user
      credential:identity-link:get: Allows the authenticated user to view all remote IDP accounts linked to it's own account
      credential:identity-link:admin:get: Allows an admin to view all remote IDP accounts linked of an user
      credential:identity-link:post: Allows the authenticated user to initiate a new identity link
      credential:identity-link:admin:post: Allows an admin to initiate a new identity link on behalf of an user
      credential:identity-link:put: Allows the authenticated user to complete it's own identity link
      credential:identity-link:admin:put: Allows and admin to complete an identity link request on behalf of an user
      credential:identity-link:delete: Allows the authenticated user to delete an identity link
      credential:identity-link:admin:delete: Allows an admin to delete an identity link on behalf of an user
      credential:identity-link:patch: Allows the authenticated use to activate it's own identity link
      credential:identity-link:admin:patch: Allows an admin to activate an identity link on behalf on an user
      credential:identity-link:profile:post: Allows to retrieve profile data from any social provider
      credential:password:manager: Allows an admin user or an application to set a password on behalf of the user
      credential:password-policy:get: Allows to retreive the configured password policy

paths:
  /credential/v1/{user_id}/primary-email:
    get:
      security:
        - OAuth2: [ 'credential:primary-email:get','credential:primary-email:admin:get' ]
      operationId: getPrimaryEmail
      summary: Returns the primary email for the user
      description: >-
        The endpoint is protected and allows end users(CIAM or admin) to get the primary email.
        The regular users must have 'credential:primary-email:get' scope and admin users must have the
        'credential:primary-email:admin:get' scope in order to view another user's primary email.
      parameters:
        - name: user_id
          in: path
          required: true
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
      responses:
        200:
          description: Primary Email details
          schema:
            $ref: '#/definitions/PrimaryEmailResponse'
        204:
          description: No Primary Email
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Unauthorized'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/primary-email-request:
    post:
      operationId: createPrimaryEmailRequest
      summary: Request to make an email address the user's primary email.
      security:
        - OAuth2: [ 'credential:primary-email:post','credential:primary-email:admin:post' ]
      description: |-
        When this API is called, it triggers the following process:

          * The email address is added to the user's profile if it wasn't already included. If the email address is added, it will get the type 'home' by default.
          * A verification email is sent to the requested primary email address containing a verification link.
          * When the recipient clicks on the link to confirm, he is asked to login to make sure that the person that has access to the email box is the same person as the person that is the legitimate user of the identity.
          If the recipient successfully logs in, the user's primary email address is updated to the requested value.

        Multiple calls to this endpoint can be done:
          * Every call will generate a new email, so this API-call can be (mis)used to have an end user re-confirm his primary email address.

        A user's profile can have multiple email addresses:
          * The list of all emails for a user can be obtained through the iWelcome SCIM API. The credential API reveals only the ones that are primary or are requested to become primary.
          * Until the 'new' email address is confirmed by the end user, the primary email address of the end user will not be changed; it will still have the 'old' value.

        If the authenticated user has the scope 'credential:primary-email:post', it can create a new primary email request.
        An admin user can create a new primary email request only if the scope 'credential:primary-email:admin:post' is present.
      parameters:
        - name: primary_email_request
          in: body
          required: true
          schema:
            $ref: '#/definitions/NewPrimaryEmailRequest'
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        200:
          description: >-
            The request is accepted and immediately executed because the email
            address was already part of the profile and was also already
            verified. Empty response.
          schema:
            $ref: '#/definitions/PrimaryEmailRequestResponse'
        202:
          description: >-
            The request is accepted. An email will be sent to the end user to
            confirm that he has access to the associated email box.
          schema:
            $ref: '#/definitions/PrimaryEmailRequestResponse'
        400:
          description: 'Bad Request: CRE900006'
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Authorization failure, error code: CRE000002'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: 'User not found, error code: CRE000004'
          schema:
            $ref: '#/definitions/ErrorResponse'
        409:
          description: |-
            The request is declined because: >-
              * The email address is already a
            unique identifier for another identity within the same segment
              * Redirect-URL is not whitelisted
              * Email domain not allowed (white/blacklisting)
            error code: CRE000005, CRE000006 or CRE000007
          schema:
            $ref: '#/definitions/ErrorResponse'
        422:
          description: 'Not a valid email address, error code: CRE000001'
          schema:
            $ref: '#/definitions/ErrorResponse'
        429:
          description: 'Too many requests, error code: CRE000008'
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: 'Internal server error, error code: CRE000009'
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/primary-email-confirmation:
    post:
      operationId: createPrimaryEmailConfirmation
      summary: Endpoint to confirm a user's email address
      security:
        - OAuth2: ['credential:primary-email:post']
      description: >-
        When a user's email address needs to be verified, it sends a link to the user's email address. When that link
        is clicked on, the user needs to login (if not already) before this protected endpoint can be invoked to
        confirm the email address and make it primary. The provided access token must have the 'credential:primary-email:post' scope.

        The reason for protecting this endpoint is to make sure that the user that clicks on the confirmation link, is
        the legitimate user of the account. This may not be in the case in the following scenario's:
          * The end-user made a typo when entering his 'new' primary e-mail request; he may have entered d.johnsson@mydomain.com instead of d.johnson@mydomain.com. If Dan Johnsson clicks on the link, he has in fact taken-over the account and Dave Johnson has lost access to his account because logging in with the original email address (e.g. davejohnson@mydomain.com) and password is no longer working.
          * An end-user may have left a device on which he is logged-in 'open' and a malicious person can change the e-mail address unnoticed. Again, the legitimate user would loose access to the account.

          iWelcome considers this as a best practice in the context of  'security and privacy by design'. Customers who prefer a more user-friendly process without the need for logging in, can consider using the "/credential/v1/public/primary-email-confirmation" endpoint instead.
          >

          The confirmation has the following effects on the attribute value metadata (AVM) of the new email address:

          * currency.LastVerification is set to current timestamp
          * accuracy.Validation is set to _valid_
          * accuracy.VerificationLevel is set to 1
          * accuracy.VerificationMethod is set to _Proof of Possession_
          * accuracy.Verifier is set to _Provider_
          * provenance.provider is set to  the configured data controller for the segment
          * provenance.pedigree is set to _self-asserted_
      parameters:
        - name: primary_email_confirmation
          in: body
          required: true
          description: the token and the authenticated user
          schema:
            $ref: '#/definitions/NewPrimaryEmailConfirmation'
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        200:
          description: The requested email address is now primary
          schema:
            $ref: '#/definitions/PrimaryEmailConfirmationResponse'
        401:
          description: 'Authorization failure, error code: CRE000002'
          schema:
            $ref: '#/definitions/ErrorResponse'
        409:
          description: 'Invalid or expired OTP, error code: CRE000055'
          schema:
            $ref: '#/definitions/ErrorResponse'
        422:
          description: >-
            the email address is no longer part of the user's profile, error
            code: CRE000013
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/public/primary-email-confirmation:
    post:
      operationId: createPrimaryEmailConfirmationPublic
      summary: Unprotected endpoint to confirm a user's email address without authenticating the enduser.
      description: >-
        _Customers need to request iWelcome to expose this endpoint,_ which by default is not the case, since usage does not follow the principle of 'security by design'. The benefit of this endpoint above the protected version is that  the end-user will get a better user-experience since he doesn't have to login when confirming the new e-mail address.


        This endpoint is the same as the /credential/v1/primary-email-request endpoint, but without the need for the end-user to authenticate himself. As a consequence, a 401 response is not applicable.

      parameters:
        - name: primary_email_confirmation
          in: body
          required: true
          description: the token and the authenticated user
          schema:
            $ref: '#/definitions/NewPrimaryEmailConfirmation'
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        200:
          description: The requested email address is now primary
          schema:
            $ref: '#/definitions/PrimaryEmailConfirmationResponse'
        404:
          description: >-
            the token was not found, has been used before, or has expired, error
            code: CRE000010, CRE000011, CRE000012
          schema:
            $ref: '#/definitions/ErrorResponse'
        422:
          description: >-
            the email address is no longer part of the user's profile, error
            code: CRE000013
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/{user_id}/primary-phone-number:
    get:
      security:
        - OAuth2: [ 'credential:primary-phonenumber:get','credential:primary-phonenumber:admin:get' ]
      operationId: getPrimaryPhoneNumber
      summary: Returns the current primary phone number
      description: >-
        The endpoint is protected and allows end users(CIAM or admin) to get the current primary phone number.
        The regular users must have 'credential:primary-phonenumber:get' scope and admin users must have the
        'credential:primary-phonenumber:admin:get' scope in order to view another user's primary phone number.
      parameters:
        - name: user_id
          in: path
          required: true
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
      responses:
        200:
          description: Primary Phone number details
          schema:
            $ref: '#/definitions/PrimaryPhoneNumberResponse'
        204:
          description: No Primary Phone Number
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Unauthorized'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/primary-phone-number-request:
    post:
      security:
        - OAuth2: [ 'credential:primary-phonenumber:post','credential:primary-phonenumber:admin:post' ]
      operationId: createPrimaryPhoneNumberRequest
      summary: Request to make a phone number the user's primary phone number.
      description: |-
        When this API is called, it triggers the following process:

          * The phone number is added to the user's profile if it wasn't already included. If the phone number is added, it will get the type 'home' by default. If the phone number is already verified, it will be made primary without sending an SMS for validation.
          * A SMS is sent to the requested primary phone number containing a OTP token.
          * When calling /primary-phone-number-confirmation with the previously obtained OTP token, the phone number becomes primary.

        Multiple calls to this endpoint can be done:
          * Every call will generate a new SMS, so this API-call can be (mis)used to have an end user re-confirm his primary phone number.

        A user's profile can have multiple phone numbers:
          * The list of all phone numbers for a user can be obtained through the iWelcome SCIM API. The credential API reveals only the ones that are primary or are requested to become primary.
          * Until the 'new' phone number is confirmed by the end user, the primary phone number of the end user will not be changed; it will still have the 'old' value.

        If the authenticated user has the scope 'credential:primary-phonenumber:post', it can create a new primary phone number request.
        An admin user can create a new primary phone number request only if the scope 'credential:primary-phonenumber:admin:post' is present.
      parameters:
        - name: primary_phone_number_request
          in: body
          required: true
          schema:
            $ref: '#/definitions/NewPrimaryPhoneNumberRequest'
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        200:
          description: >-
            The phone number is made primary, no further validation is required.
          schema:
            $ref: '#/definitions/PrimaryPhoneNumberRequestResponse'
        202:
          description: >-
            The request is accepted and the process of validating the phone number is started.
          schema:
            $ref: '#/definitions/PrimaryPhoneNumberRequestResponse'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Authorization failure, error code: CRE000002'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: 'User not found, error code: CRE000004'
          schema:
            $ref: '#/definitions/ErrorResponse'
        409:
          description: |-
            The request is declined because: >-
              * The phone number is already a
            unique identifier for another identity within the same segment
            error code: CRE000053
          schema:
            $ref: '#/definitions/ErrorResponse'
        429:
          description: 'Too many requests, error code: CRE000008'
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: 'Internal server error, error code: CRE000009'
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/primary-phone-number-confirmation:
    post:
      operationId: createPrimaryPhoneNumberConfirmation
      summary: Endpoint to confirm a user's phone number
      security:
        - OAuth2: ['credential:primary-phonenumber:post']
      description: >-
        When a user's phone number needs to be verified, it sends a SMS with the OTP token to the
        user's phone number. When that token is provided to this endpoint along with an access token containing the
        'credential:primary-phonenumber:post' scope, the user's phone number will become primary.

          The confirmation has the following effects on the attribute value metadata (AVM) of the new phone number:

          * currency.LastVerification is set to current timestamp
          * accuracy.Validation is set to _valid_
          * accuracy.VerificationLevel is set to 1
          * accuracy.VerificationMethod is set to _Proof of Possession_
          * accuracy.Verifier is set to _Provider_
          * provenance.provider is set to  the configured data controller for the segment
          * provenance.pedigree is set to _self-asserted_
      parameters:
        - name: primary_phone_number_confirmation
          in: body
          required: true
          description: the token and the authenticated user
          schema:
            $ref: '#/definitions/NewPrimaryPhoneNumberConfirmation'
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        200:
          description: The requested phone number is now primary
          schema:
            $ref: '#/definitions/PrimaryPhoneNumberConfirmationResponse'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Authorization failure, error code: CRE000002'
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: >-
            the token was not found, has been used before, or has expired, error
            code: CRE000053
          schema:
            $ref: '#/definitions/ErrorResponse'
        422:
          description: >-
            the phone number is no longer part of the user's profile, error
            code: CRE000055
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: 'Internal server error, error code: CRE000042'
          schema:
            $ref: '#/definitions/ErrorResponse'

  /credential/v2/primary-phone-number-request:
    post:
      security:
        - OAuth2: [ 'credential:primary-phonenumber:post','credential:primary-phonenumber:admin:post' ]
      operationId: createPrimaryPhoneNumberRequestV2
      summary: Request to make a phone number the user's primary phone number.
      description: |-
        When this API is called, it triggers the following process:

          * The phone number is added to the user's profile if it wasn't already included. If the phone number is added, it will get the type 'home' by default. If the phone number is already verified, it will be made primary without sending an SMS for validation.
          * A SMS is sent to the requested primary phone number containing a OTP token.
          * When calling /primary-phone-number-confirmation with the previously obtained OTP token, the phone number becomes primary.

        Multiple calls to this endpoint can be done:
          * Every call will generate a new SMS, so this API-call can be (mis)used to have an end user re-confirm his primary phone number.

        A user's profile can have multiple phone numbers:
          * The list of all phone numbers for a user can be obtained through the iWelcome SCIM API. The credential API reveals only the ones that are primary or are requested to become primary.
          * Until the 'new' phone number is confirmed by the end user, the primary phone number of the end user will not be changed; it will still have the 'old' value.

        If the authenticated user has the scope 'credential:primary-phonenumber:post', it can create a new primary phone number request. The authenticated user id will be used for performing the operation.
        An admin user can create a new primary phone number request only if the scope 'credential:primary-phonenumber:admin:post' is present. If this scope is present, then the request must contain the user id, otherwise the request will fail with 400 Bad Request, indicating that the user_id is not valid.
      parameters:
        - name: primary_phone_number_request
          in: body
          required: true
          schema:
            $ref: '#/definitions/NewPrimaryPhoneNumberRequest'
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        200:
          description: >-
            The phone number is made primary, no further validation is required.
          schema:
            $ref: '#/definitions/PrimaryPhoneNumberRequestResponse'
        202:
          description: >-
            The request is accepted and the process of validating the phone number is started.
          schema:
            $ref: '#/definitions/PrimaryPhoneNumberRequestResponse'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Authorization failure, error code: CRE000002'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: 'User not found, error code: CRE000004'
          schema:
            $ref: '#/definitions/ErrorResponse'
        409:
          description: |-
            The request is declined because: >-
              * The phone number is already a
            unique identifier for another identity within the same segment
            error code: CRE000053
          schema:
            $ref: '#/definitions/ErrorResponse'
        429:
          description: 'Too many requests, error code: CRE000008'
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: 'Internal server error, error code: CRE000009'
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v2/primary-phone-number-confirmation:
    post:
      operationId: createPrimaryPhoneNumberConfirmationV2
      summary: Endpoint which can be used to confirm the authenticated user's primary phone number, or by an admin to confirm the phone number on behalf of another user.
      security:
        - OAuth2: [ 'credential:primary-phonenumber:post', 'credential:primary-phonenumber:admin:post' ]
      description: >-
        When a user's phone number needs to be verified, it sends a SMS with the OTP token to the
        user's phone number. When the authenticated user is verifying it's own phone number, the scope 'credential:primary-phonenumber::post' is required.
        If an admin is performing this operation on behalf of the user, the scope 'credential:primary-phonenumber:admin:post' is needed. If this scope is present, then the request must contain the user id, otherwise the request will fail with 400 Bad Request, indicating that the user_id is not valid.
        Assuming the access token has the correct scope assigned, the user's phone number will become primary.

          The confirmation has the following effects on the attribute value metadata (AVM) of the new phone number:

          * currency.LastVerification is set to current timestamp
          * accuracy.Validation is set to _valid_
          * accuracy.VerificationLevel is set to 1
          * accuracy.VerificationMethod is set to _Proof of Possession_
          * accuracy.Verifier is set to _Provider_
          * provenance.provider is set to  the configured data controller for the segment
          * provenance.pedigree is set to _self-asserted_
      parameters:
        - name: primary_phone_number_confirmation
          in: body
          required: true
          description: the token and the authenticated user
          schema:
            $ref: '#/definitions/PrimaryPhoneNumberConfirmationRequest'
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        200:
          description: The requested phone number is now primary
          schema:
            $ref: '#/definitions/PrimaryPhoneNumberConfirmationResponse'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Authorization failure, error code: CRE000002'
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: >-
            The token was not found, has been used before, or has expired, error
            code: CRE000053
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Valid access token provided, but with required scopes missing'
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: 'Internal server error, error code: CRE000042'
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/identity-links/profile:
    post:
      security:
        - OAuth2: [ 'credential:identity-link:profile:post']
      operationId: profileIdentityLink
      summary: An endpoint to retrieve profile data from any social provider
      description: >-
        An endpoint to retrieve profile data from any social provider.
        The access_token needs to have the scope: 'credential:identity-link:profile:post'.
      parameters:
        - name: profileRequest
          in: body
          description: 'profile request'
          required: true
          schema:
            $ref: '#/definitions/ProfileIdentityLinkRequest'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/ProfileIdentityLinkResponse'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
  /credential/v1/identity-links:
    post:
      security:
        - OAuth2: [ 'credential:identity-link:post', 'credential:identity-link:admin:post' ]
      operationId: initIdentityLinks
      summary: An endpoint to initiate the account linking process before redirecting the user to the (social) identity provider for login.
      description: >-
        An endpoint to initiate the account linking process before redirecting the user to the (social) identity provider for login.
        The access_token needs to have one of the following scopes: 'credential:identity-link:post' is needed when the authenticated user is initiating its own identity link
        and scope 'credential:identity-link:admin:post' is needed when the initiated link is made by an application.
        This endpoint returns parameter values that must be sent to the OAuth specified /authorize endpoint at the external identity provider):
          - The value of the 'id' must be passed on to the identity provider as value for the 'state' parameter, as specified by OAuth.
          - The value of the 'nonce' must simply be used as a 'nonce' parameter.
      parameters:
        - name: socialProvider
          in: body
          description: 'Social provider name'
          required: true
          schema:
            $ref: '#/definitions/IdentityLinkRequest'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/PendingIdentityLinkResponse'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized

    get:
      operationId: getIdentityLinks
      security:
        - OAuth2: [ 'credential:identity-link:get','credential:identity-link:admin:get' ]
      summary: Get an overview of all linked accounts
      parameters:
        - name: user_id
          in: query
          description: >-
            If this query parameter is provided, the access_token must have scope 'credential:identity-link:admin:get' as authorisation to query other users' identity-links.
            If the scope 'credential:identity-link:get' is present, the endpoint will return the identity-links for the authenticated user.
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/IdentityLinksResponse'
  /credential/v1/identity-links/activate/{linkId}:
    patch:
      security:
        - OAuth2: [ 'credential:identity-link:patch','credential:identity-link:admin:patch' ]
      operationId: activateIdentityLink
      summary: Method used to activate the identity link.
      description: >-
        Method used to activate the identity link. Invoking this method changes the status of the identity-link from 'inactive' or 'pending' to 'active'.
        The access_token needs to have one of the following scopes: 'credential:identity-link:patch' is needed when the authenticated user is activating its own IDP and scope 'credential:identity-link:admin:patch'
        is needed when the link is activated by an application. In this situation, the user id of the identity link with 'linkId' is set to the one from the payload.
      parameters:
        - name: linkId
          in: path
          description: identifier for the linked account
          required: true
          type: string
        - name: ActivateLinkRequest
          in: body
          required: true
          description: the activate identity link request
          schema:
            $ref: '#/definitions/ActivateIdentityLinkRequest'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/IdentityLink'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/identity-links/{id}:
    put:
      security:
        - OAuth2: [ 'credential:identity-link:put','credential:identity-link:admin:put' ]
      operationId: linkAccount
      summary: The endpoint used to complete the identity link.
      description: >-
        Endpoint used to link a (social) identity to the authenticated user. The 'state' parameter that the OAuth identity provider provided in the call-back must be used.
        The access_token needs to have one of the following scopes: 'credential:identity-link:put' is needed when the authenticated user is linking its own IDP and scope 'credential:identity-link:admin:put'
        is needed when the link is made by an application. In this situation, the user id of the identity link with 'authorizationCode' is set to the one from the payload.
      parameters:
        - name: id
          in: path
          description: identifier for the linked account
          required: true
          type: string
        - name: OAuthIdentityLinkRequest
          in: body
          required: true
          description: the Authorization codet
          schema:
            $ref: '#/definitions/OAuthIdentityLinkRequest'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/IdentityLink'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
    delete:
      security:
        - OAuth2: [ 'credential:identity-link:delete','credential:identity-link:admin:delete' ]
      operationId: unlinkAccount
      summary: Endpoint used to unlink a (social) account from the authenticated user.
      description: >-
        Endpoint used to unlink a (social) account from the authenticated user.
        The access_token needs to have one of the following scopes 'credential:identity-link:delete' is needed when the authenticated user is deleting its own identity link and
        to delete a link of somebody else the access_token needs to have scope 'credential:identity-link:admin:delete' as authorisation.
      parameters:
        - name: id
          in: path
          description: identifier for the linked account
          required: true
          type: string
        - name: DeleteLinkRequest
          in: body
          required: true
          schema:
            $ref: '#/definitions/DeleteIdentityLinkRequest'
      responses:
        200:
          description: OK
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
  /credential/v1/password:
    patch:
      security:
        - OAuth2: [ 'credential:password:manager' ]
      operationId: setPassword
      summary: Set password for provided user id
      description: >-
        This is a protected endpoint and allows end users(CIAM or admin) to set their passwords.
        Admin users must have the 'credential:password:manager' scope in order to set another user's password.
      parameters:
        - name: Authorization
          in: header
          description: The authorization header must contain 'Bearer <access_token>'
          required: true
          type: string
        - name: passwordRequest
          in: body
          required: true
          schema:
            $ref: '#/definitions/SetPasswordRequest'
      responses:
        204:
          description: Password has been successfully updated
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/password-policy:
    get:
      security:
        - OAuth2: [ 'credential:password-policy:get' ]
      operationId: getPasswordPolicy
      summary: Get password policy
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/PasswordPolicyResponse'
        400:
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/users/{user_id}/password/metadata:
    get:
      security:
        - OAuth2: [ ]
      operationId: getPasswordMetadata
      summary: Get password metadata
      description: >-
        Obtain information about the user's password.
      parameters:
        - name: user_id
          in: path
          required: true
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        200:
          description: Password info is returned (without the password itself)
          schema:
            $ref: '#/definitions/PasswordMetadataResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
  /credential/v1/users/{user_id}/password:
    put:
      operationId: changePassword
      summary: Change password for provided user id
      description: >-
        The Set Password API is a protected endpoint and allows end-users(CIAM) to change their password.
                For security reasons, the authenticated user needs to provide either one of:
                  * current password
                  * ID-token
      parameters:
        - name: user_id
          in: path
          required: true
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
        - name: Authorization
          in: header
          description: >-
            The end-user's access_token must be provided as a Bearer token, for example "Bearer 2YotnFZFEjr1zCsicMWpAA".
          required: true
          type: string
        - name: changePasswordRequest
          in: body
          required: true
          schema:
            $ref: '#/definitions/ChangePasswordRequest'
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        200:
          description: Password has been successfully set or updated.
          schema:
            $ref: '#/definitions/PasswordMetadataResponse'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Unauthorized'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: >-
            'User didn't provide the right current password'
          schema:
            $ref: '#/definitions/ErrorResponse'

definitions:
  OAuthIdentityProviderName:
    type: string
  NewPrimaryEmailRequest:
    type: object
    properties:
      user_id:
        type: string
        pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
      primary_email:
        type: string
        pattern: ^[a-zA-Z0-9!#$%&'*+-/=?^_`{|}~]+(?:\.[a-zA-Z0-9!#$%&'*+-/=?^_`{|}~]+)*@(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,7}$
        maxLength: 254
      redirect_url:
        type: string
        pattern: ^((((https?)://))(%[0-9A-Fa-f]{2}|[-()_.!~*';/?:@&=+$,A-Za-z0-9])+)([).!';/?:,][[:blank:]])?$
        description: >-
          After the user has successfully confirmed the new email address he
          will be redirected to this url. The url may indicate some iWelcome
          page or it may indicate a web page from a 3rd party. Url whitelisting
          is applied.
      id_token:
        $ref: '#/definitions/IDtoken'
    required:
      - user_id
      - primary_email
  PrimaryEmailRequestResponse:
    type: object
    properties:
      id:
        type: string
      user_id:
        type: string
      requested_primary_email:
        type: string
      request_datetime:
        type: string
        format: date-time
      email_verification_expiration_datetime:
        type: string
        format: date-time
      redirect_url:
        type: string
    required:
      - requested_primary_email
      - request_datetime
      - user_id
      - redirect_url
  NewPrimaryEmailConfirmation:
    type: object
    properties:
      token:
        type: string
        description: >-
          It is a random string which is part of the confirmation email.
          The confirmation email is sent when the API which triggers a primary email request is called.
          The result of calling that API would be an email sent to the user, containing
          a link on which the user must click in order to confirm the primary email, and that link contains the token.
        pattern: ^[\p{L}\p{Zs}0-9\.,_'\-]+$
        maxLength: 100
    required:
      - token
  PrimaryEmailConfirmationResponse:
    type: object
    properties:
      user_id:
        type: string
      primary_email:
        type: string
      previous_primary_email:
        type: string
      redirect_url:
        type: string
    required:
      - user_id
      - primary_email
      - redirect_url
    description: >-
      By including the previous primary email, a message can be presented to the
      user that no emails will be sent to that email address.
  NewPrimaryPhoneNumberRequest:
    type: object
    properties:
      user_id:
        type: string
        pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
      primary_phone_number:
        type: string
        pattern: ^(tel:)?((?:\+|00)[1-9]|0)(|\-)(\d)?((\(\d{1,3}\))|(\d{1,3}))(\.|\-|\/|\s)?((\(\d{1,}\))|(\d{1,}))(\.|\-|\/|\s)?((\(\d{1,4}\))|(\d{1,4}))(\.|\-|\/|\s)?(((\(\d{1,4}\))|(\d{1,4}))(\.|\-|\/|\s)?((\(\d{1,4}\))|(\d{1,4}))?)(;(phone-context|ext|isub)=[^-])?(\S)$
        maxLength: 30
      locale:
        type: string
        pattern:  ^[a-zA-Z_-]+$
        maxLength: 5
      id_token:
        $ref: '#/definitions/IDtoken'
      transmission_method:
        type: string
        pattern: ^[\p{L}\p{Zs}0-9\.,_'\-]+$
        maxLength: 32
        description: >-
          The channel through which the OTP will be sent to the user in order to confirms its primary phone number.
          Examples: "sms", "voice", etc.
    required:
      - primary_phone_number
  PrimaryPhoneNumberRequestResponse:
    type: object
    properties:
      user_id:
        type: string
      requested_primary_phone_number:
        type: string
      requested_locale:
        type: string
      request_datetime:
        type: string
        format: date-time
    required:
      - requested_primary_phone_number
      - request_datetime
      - user_id
  PrimaryPhoneNumberResponse:
    type: object
    properties:
      primary_phone_number:
        type: string
      set_date:
        type: string
        format: date-time
      verified:
        description: Describe if the primary phone number was verified or not. If the phone number is verified then the *true* value will be returned otherwise *false*.
        type: boolean
  PrimaryEmailResponse:
    type: object
    properties:
      primary_email:
        type: string
      set_date:
        type: string
        format: date-time
      verified:
        description: Describe if the primary email was verified or not. If the email is verified then the *true* value will be returned otherwise *false*.
        type: boolean
  NewPrimaryPhoneNumberConfirmation:
    type: object
    properties:
      verification_code:
        type: string
        pattern: ^[\p{L}\p{Zs}0-9\.,_'\-]+$
        maxLength: 100
      phone_number:
        type: string
        pattern: ^(tel:)?((?:\+|00)[1-9]|0)(|\-)(\d)?((\(\d{1,3}\))|(\d{1,3}))(\.|\-|\/|\s)?((\(\d{1,}\))|(\d{1,}))(\.|\-|\/|\s)?((\(\d{1,4}\))|(\d{1,4}))(\.|\-|\/|\s)?(((\(\d{1,4}\))|(\d{1,4}))(\.|\-|\/|\s)?((\(\d{1,4}\))|(\d{1,4}))?)(;(phone-context|ext|isub)=[^-])?(\S)$
        maxLength: 30
    required:
      - verification_code
      - phone_number
  PrimaryPhoneNumberConfirmationRequest:
    type: object
    properties:
      verification_code:
        type: string
        pattern: ^[\p{L}\p{Zs}0-9\.,_'\-]+$
        maxLength: 100
      phone_number:
        type: string
        pattern: ^(tel:)?((?:\+|00)[1-9]|0)(|\-)(\d)?((\(\d{1,3}\))|(\d{1,3}))(\.|\-|\/|\s)?((\(\d{1,}\))|(\d{1,}))(\.|\-|\/|\s)?((\(\d{1,4}\))|(\d{1,4}))(\.|\-|\/|\s)?(((\(\d{1,4}\))|(\d{1,4}))(\.|\-|\/|\s)?((\(\d{1,4}\))|(\d{1,4}))?)(;(phone-context|ext|isub)=[^-])?(\S)$
        maxLength: 30
      user_id:
        type: string
        pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
    required:
      - verification_code
      - phone_number

  PrimaryPhoneNumberConfirmationResponse:
    type: object
    properties:
      user_id:
        type: string
      primary_phone_number:
        type: string
      previous_primary_phone_number:
        type: string
    required:
      - user_id
      - primary_phone_number
    description: >-
      By including the previous primary phone number, a message can be presented to the
      user that no tokens will be sent to that phone number.

  DurationResponse:
    type: object
    description: >-
      Remaining validity period for a password that almost expires. This duration is only provided during the password expiry warning period.
    properties:
      days:
        type: integer
      hours:
        type: integer
      minutes:
        type: integer
      seconds:
        type: integer
  OAuthIdentityLinkRequest:
    type: object
    properties:
      authorization_code:
        description: Authorization code as received from the OAuth Identity Provider
        type: string
        pattern: ^[\p{L}\/p\\{Zs}0-9\.,_'\-%=&]+$
      id_token:
        $ref: '#/definitions/IDtoken'
      user_id:
        type: string
    required:
      - authorization_code
  IdentityLinkStatus:
    type: string
    description: >-
      The values of this field have the following meaning:
      - pending. This status indicates that the process to create an identity link is pending on interaction with the external to the identity provider. Typically this state applies when the user's user agent is directed to the identity-provider and the identity provider hasn't yet redirected the user back to iWelcome. iWelcome may remove links with status 'pending' if the link is not confirmed within a configured period.
      - inactive. This status indicates that some identity validation process is needed before the linked account can be used as a credential to log in. An example of such a validation process is identity matching; a process to confirm that the profile of the identity that is being linked has sufficient correspondence to the profile in iWelcome. iWelcome may remove links with status 'inactive' if the link is not confirmed within a configured period.
      - active. This status indicates a linked identity
    enum:
      - pending
      - inactive
      - active
  Nonce:
    type: string
    description: OIDC-specified string value used to associate iWelcome's client session with an ID token, and to mitigate replay attacks.
  PendingIdentityLinkResponse:
    type: object
    description: A set of attributes associated with the IdentityLink. Note that 'nonce' attribute is only returned when the identity provider supports OIDC on top of OAuth. The nonce is a security feature to prevent replay attacks and is provided only when needed.
    required:
      - id
      - identity_provider_name
      - status
      - creation_date
    properties:
      id:
        type: string
        description: This identifier for the (pending) identity link must be passed to the external OAuth identity provider as the OAuth 'state' parameter. After the redirect, the state parameter identifies the pending identity-link that must be progressed to the next state.
      identity_provider_name:
        $ref: '#/definitions/OAuthIdentityProviderName'
      status:
        $ref: '#/definitions/IdentityLinkStatus'
      creation_date:
        $ref: '#/definitions/CreationDate'
      nonce:
        $ref: '#/definitions/Nonce'
      user_id:
        type: string
      redirectUrl:
        type: string
  IdentityLink:
    type: object
    description: A set of attributes associated with the IdentityLink. Note that 'nonce' attribute is only returned as part of a response to the POST and not returned in responses to other methods. The nonce is a security feature to prevent replay attacks and is provided only when needed.
    required:
      - id
      - identity_provider_name
      - status
      - creation_date
      - sub
    properties:
      id:
        type: string
        description: This identifier for the (pending) identity link must be passed to the external OAuth identity provider as the OAuth 'state' parameter. After the redirect, the state parameter identifies the pending identity-link that must be progressed to the next state.
      identity_provider_name:
        $ref: '#/definitions/OAuthIdentityProviderName'
      status:
        $ref: '#/definitions/IdentityLinkStatus'
      creation_date:
        $ref: '#/definitions/CreationDate'
      user_id:
        type: string
      sub:
        $ref: '#/definitions/Sub'
  CreationDate:
    type: string
    description: date and time on which the (social) account was linked to the account in iWelcome. When the status of a link changes, the creation_date does not change.
    format: date-time
  Sub:
    type: string
    description: A Subject Identifier is a locally unique and never reassigned identifier within the Issuer (external identity provider) for the End-User, which is intended to be consumed by the Client (iWelcome). The sub may have type 'public' or 'pairwise'.
  IdentityLinkRequest:
    type: object
    required:
      - identity_provider
    properties:
      identity_provider:
        $ref: '#/definitions/OAuthIdentityProviderName'
      id_token:
        $ref: '#/definitions/IDtoken'
  ActivateIdentityLinkRequest:
    type: object
    properties:
      user_id:
        type: string
        minLength: 1
        pattern: ^[\S]+$
      idp_user_id:
        type: string
        minLength: 1
        pattern: ^[\S]+$
      id_token:
        $ref: '#/definitions/IDtoken'
  ProfileIdentityLinkRequest:
    type: object
    required:
      - link_id
      - authorization_code
    properties:
      link_id:
        type: string
      redirect_url:
        type: string
        description: Represents the redirect url which was used in the request for initiating the identity link request. If this url is different than the one used in the init identity link request, the request will fail.
      authorization_code:
        description: Authorization code as received from the OAuth Identity Provider
        type: string
        pattern: ^[\p{L}\/p\\{Zs}0-9\.,_'\-%=&]+$
  ProfileIdentityLinkResponse:
    type: object
    description: data received from the remote IDP
    additionalProperties:
      type: object
  DeleteIdentityLinkRequest:
    type: object
    properties:
      id_token:
        $ref: '#/definitions/IDtoken'
  IdentityLinksResponse:
    type: array
    items:
      $ref: '#/definitions/IdentityLink'
  PasswordMetadataResponse:
    type: object
    properties:
      set_date:
        type: string
        description: Date and time on which the current password was set.
        format: date-time
      password_provided:
        type: boolean
        description: Boolean that indicates if a password is set for the user.
      is_expired:
        description: Boolean that indicates if the password has expired.
        type: boolean
      validity_duration:
        $ref: '#/definitions/DurationResponse'
      expiration_date:
        type: string
        description: The date and time on which the password expires. This information is only provided during the password expiration period.
        format: date-time
  ChangePasswordRequest:
    required:
      - password
    properties:
      password:
        type: string
        description: A string representing the password to assign for the user specified.
      current_password:
        type: string
        description: A string representing the user's current password. This is mandatory
      id_token:
        $ref: '#/definitions/IDtoken'
  SetPasswordRequest:
    properties:
      userId:
        type: string
        pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
        description: A string representing the id of the user to set the password for.
      password:
        type: string
        description: A string representing the password to assign for the user specified.
  IDtoken:
    type: string
    description: >-
      An ID-token is the primary extension that OpenID Connect makes to OAuth 2.0 to enable End-Users to be Authenticated.
      It is a security token that contains Claims about the Authentication of an End-User, such as auth_time and acr.


      Depending on configuration, the credential API _may_ evaluate the values of the auth_time and acr claims. The auth_time claim may be used to check if the user was authenticated at a sufficiently recent moment. The acr claim may be used to check if the user was authenticated sufficiently strong, i.e. with 2FA. The required maximum age and acr value can be configured indepently for each type of credential; primary email, primary phone and password.

      If reauthentication is needed, a 403 error response is returned.

  PasswordPolicyResponse:
    type: object
    properties:
      maxPasswordAge:
        type: string
        description: >-
          Specifies the maximum length of time that you can have the same password. After this time period, the password
          expires and you must create a new one. The value of this attribute is a duration and a value of PT0S disables password expiration.
        example: P183D
      warningInterval:
        type: string
        description: >-
          Specifies the maximum length of time before a user's password actually expires that the server begins to
          include warning notifications for that user. The value of this attribute is a duration and a value of PT0S disables the warning interval.
        example: P14D
      minimumLength:
        type: integer
        description: >-
          Specifies the minimum number of characters that a password must contain.
        example: 8
      minimumLowercaseCharacters:
        type: integer
        description: >-
          Specifies the minimum number of lowercase characters that a password must contain.
        example: 1
      minimumUppercaseCharacters:
        type: integer
        description: >-
          Specifies the minimum number of uppercase characters that a password must contain.
        example: 1
      minimumDecimals:
        type: integer
        description: >-
          Specifies the minimum number of decimals that a password must contain.
        example: 1
      minimumSpecialCharacters:
        type: integer
        description: >-
          Specifies the minimum number of special characters that a password must contain.
        example: 1
      minimumNumberOfCategoriesToBeUsed:
        type: integer
        description: >-
          Specifies the minimum number of categories that a password must contain.
        example: 4
      forbiddenLeadingChars:
        type: string
        description: >-
          Specifies the leading characters that a password must not contain.
        example: abc
      forbiddenTrailingChars:
        type: string
        description: >-
          Specifies the trailing characters that a password must not contain.
        example: xyz
      accountLockout:
        $ref: '#/definitions/AccountLockout'
      passwordHistory:
        $ref: '#/definitions/PasswordHistory'
      forcePasswordChange:
        $ref: '#/definitions/ForcePasswordChange'

  AccountLockout:
    type: object
    properties:
      enabled:
        type: boolean
        description: >-
          Specifies if the account lockout functionality is enabled.
        example: true
      maximumBlockTime:
        type: string
        description: >-
          This represents the maximum time that an account can be blocked. After this time expires, the user can login again.
        example: PT24H
      blockingTimePeriod:
        type: string
        description: >-
          Time duration for which an account will be blocked. After the blockingTimePeriod expires, the user will be
          able to attempt to authenticate again.
        example: PT2M
      maxFailedLoginAttempts:
        type: integer
        description: >-
          Specifies the maximum number of consecutive failed login attempts after which the account will be blocked.
        example: 5
      multiplyingFactor:
        type: integer
        description: >-
          Specifies the factor used to increase the blocking duration for each successive account lockout. For example
          if the user has been blocked for 2 minutes, and after 2 minutes it tries again for a number of times equal to
          maxFailedLoginAttempts, the account will be blocked for 2 minutes (current block time) * multiplyingFactor.
        example: 2
      supportedModules:
        type: string
        description: >-
          Specifies the authentication modules for which the account lockout functionality is enabled.
        example: UsernameAndPassword,TwoFASms,TwoFAOptions
  PasswordHistory:
    type: object
    properties:
      enabled:
        type: boolean
        description: >-
          Specifies if the password history feature is enabled.
      size:
        type: integer
        description: >-
          Specifies the maximum history length that iWelcome keeps, after that iWelcome could purge the oldest passwords
      period:
        type: object
        properties:
          size:
            type: integer
            description: >-
              Specifies that users cannot reuse the last *X* passwords that they've used.
          length:
            type: string
            description: >-
              Specifies that users cannot reuse any password that was set during the last period *P*. This will avoid
              quickly doing *X* password changes to start re-using password the one before that.
      algorithm:
        type: string
        description: >-
          Specifies the algorithm used to encrypt the password. Possible methods that can be used for hashing mechanism are: SSHA256, SSHA512.

  ForcePasswordChange:
    type: object
    properties:
      triggers:
        type: array
        items:
          $ref: '#/definitions/ForcePasswordTrigger'
  ForcePasswordTrigger:
    type: object
    properties:
      operation:
        type: string
        description: >-
          Specifies the operation for which the trigger will operate. The following options are available: onCreate, onUpdate.
          These values of these properties consist of two SpEL expressions, and each of those will be evaluated depending
          on the API operation, as such: when a create is made, onCreate will be evaluated to decide if there is a need
          to force the user to change it's password whereas onUpdate is for updated operations.
      expression:
        type: string
        description: >-
          Specifies the expression used to decide if the user must change the password the next time they sign in.
  PasswordExpirationStatus:
    type: object
    properties:
      isExpired:
        type: boolean
      validityDuration:
        $ref: '#/definitions/DurationResponse'
      expirationDate:
        type: string
        format: date-time
  FieldErrorResource:
    type: object
    properties:
      message:
        type: string
      code:
        type: string
  PasswordValidationErrorResponse:
    type: object
    properties:
      error_code:
        type: string
        enum:
          - CRE000043
        description: >-
          Error code:
          * CRE000043: Password validation error.
      message:
        type: string
      description:
        type: string
        description: detail error message
      errors:
        type: array
        items:
          $ref: '#/definitions/FieldErrorResource'
  ErrorResponse:
    type: object
    properties:
      error_code:
        type: string
        enum:
          - CRE000001
          - CRE000002
          - CRE000003
          - CRE000004
          - CRE000005
          - CRE000006
          - CRE000007
          - CRE000008
          - CRE000009
          - CRE000010
          - CRE000011
          - CRE000012
          - CRE000013
          - CRE000014
          - CRE000015
          - CRE000016
          - CRE000017
          - CRE000018
          - CRE000019
          - CRE000020
          - CRE000021
          - CRE000022
          - CRE000023
          - CRE000024
          - CRE000030
          - CRE000031
          - CRE000032
          - CRE000033
          - CRE000034
          - CRE000035
          - CRE000036
          - CRE000037
          - CRE000038
          - CRE000039
          - CRE000040
          - CRE000041
          - CRE000042
          - CRE000044
          - CRE000045
          - CRE000046
          - CRE000047
          - CRE000048
          - CRE000049
          - CRE000050
          - CRE000051
          - CRE000052
          - CRE000053
          - CRE000054
          - CRE000055
          - CRE000056
          - CRE000057
          - CRE000058
          - CRE000059
          - CRE000060
          - CRE000061
          - CRE000062
          - CRE000063
          - CRE000064
          - CRE900001
          - CRE900002
          - CRE900003
          - CRE900004
          - CRE900005
          - CRE900006
          - CRE000105
          - CRE000106
        description: >-
          Error code:
            * CRE000001: Invalid input
            * CRE000002: Authorization failure
            * CRE000003: Permission denied
            * CRE000004: User not found
            * CRE000005: Email address already used for another account
            * CRE000006: redirect-URL is not allowed (blacklisted / not whitelisted)
            * CRE000007: email domain is not allowed (blacklisted / not whitelisted)
            * CRE000008: Too many requests
            * CRE000009: Internal server error
            * CRE000010: Token not found
            * CRE000011: Token was already used previously
            * CRE000012: Token is expired
            * CRE000013: The email address is no longer part of the user's profile.
            * CRE000014 Devicename patch success
            * CRE000015 Devicename patch failed
            * CRE000016  Eventnr 040415010 List Device Tokens Success
            * CRE000017  Eventnr 040415011 List Device Tokens Failed
            * CRE000018  Eventnr 040415020 Device token revoked success
            * CRE000019  Eventnr 040415020 Device token revoked failed

            * PATCH 400/500/422 errors:
              CRE000021  Eventnr 040615041 HTTP  400: Bad Request
              CRE000022  Eventnr 040615051 HTTP 500: Internal Error
              CRE000020  Eventnr 040415031 Device name too long or contains unacceptable characters /
                                           HTTP: 422 Name format incorrect

            * Device token 400/500 error
              CRE000023 Eventnr 040415041 HTTP  400: Bad Request
              CRE000024 Eventnr 040415041 HTTP 500: Internal Error

            * CRE000030: Social link failed
            * CRE000031: Social provider unknown error
            * CRE000032: Social provider access denied
            * CRE000033: Social unlink failed
            * CRE000034: Social provider unknown
            * CRE000035: Failed to build redirect url
            * CRE000036: Social account already linked to other account
            * CRE000037: Invalid configuration of social provider
            * CRE000039: Failed to create user.
            * CRE000040: Failed to update user.
            * CRE000041: Failed to delete user.
            * CRE000042: Something went wrong.
            * CRE000044: Password must have minimum length
            * CRE000045: Password contains forbidden character(s)
            * CRE000046: Password must contain digit(s)
            * CRE000047: Password must contain lowercase character(s)
            * CRE000048: Password must contain special character(s)
            * CRE000049: Password must contain uppercase character(s)
            * CRE000050: Password cannot contain value from name.formatted
            * CRE000051: Password cannot contain value from username
            * CRE000052: Failed to update password.
            * CRE000053: Phone number already used for another account
            * CRE000054: The phone number is no longer part of the user's profile.
            * CRE000055: OTP is not valid.
            * CRE000056: Password has already been used.
            * CRE000057: Authentication too long ago
            * CRE000058: Stronger authentication required
            * CRE000059: Authentication details unknown
            * CRE000060: Social identity provider disabled
            * CRE000061: Invalid scope
            * CRE000062: Invalid nonce
            * CRE000063: Invalid Social identity link id
            * CRE000064: Failed to retrieve authentication state.
            * CRE900001: Generic error
            * CRE900002: No resource found
            * CRE900003: Invalid message type
            * CRE900004: Unsupported media type
            * CRE900005: Method argument not valid
            * CRE900006: Email contains invalid characters
            * CRE000105: Invitation was not found or already used
            * CRE000106: Invitation data couldn't be linked to user account
      message:
        type: string
      description:
        type: string
        description: detail error message
