swagger: '2.0'
x-asee-visibility: public
host: bankapi.net
basePath: /v1/identity
info:
  description: Identity API manages online identity and credentials of users. This covers signup process, confirmations of contact points, changing and recovery of forgotten passwords and usernames. Logins from external identity providers can be linked to user profile. Hint pictures, security questions and password policy enhance user experience and security of the recovery processes.
  title: Identity API
  version: v1
tags:
  - description: Working with users
    name: Users
  - description: Working with credentials
    name: Credentials
  - description: Working with policy
    name: Policy
consumes:
  - application/json
produces:
  - application/json
schemes:
  - https
  - http
paths:

  '/policy/password-requirements':
    get:
      summary: Get password quality requirements
      description: Provides password quality requirements to enable better user experience in trusted applications where user inputs passwords
      operationId: Policy_GetPasswordRequirements
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/password-requirements'
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Policy

  '/me':
    get:
      summary: Get profile of authenticated user
      description: Provides user profile of authenticated user
      operationId: Users_GetProfile
      parameters:
        - $ref: '#/parameters/include-param'
        - $ref: '#/parameters/trim-param'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/user'
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Users
      x-asee-tags: [Shapeable]
  '/me/logins':
    post:
      summary: Add linked login for authenticated user
      description: Use to link login from external identity provider to user profile. Provider must support OAuth2 and OpenID Connect.
      operationId: Users_RegisterLinkedLogin
      parameters:
        - description: Command with parameters to register linked login
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/register-linked-login-command'
      responses:
        '204':
          description: No content - Linked login added to user profile
        '440':
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            | Problem | Description |
            |-|-|
            | [login-already-used]() | Login {login} at {provider} is already linked to another user profile |
            | [provider-not-supported]() | Provider {provider} not supported |
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Credentials
      x-asee-tags: []

  '/me/logins/{login}':
    delete:
      summary: Remove linked login for authenticated user
      operationId: Users_RemoveLinkedLogin
      parameters:
        - description: Login at external identity provider such as facebook username or gmail address
          in: path
          name: login
          required: true
          type: string
      responses:
        '204':
          description: No content - Linked login removed
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Credentials
      x-asee-tags: []

  '/me/password':
    put:
      summary: Set new password for authenticated user
      operationId: Users_ChangePassword
      parameters:
        - description: Command with parameters to change password
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/change-password-command'
      responses:
        '204':
          description: No content - Password changed
        '440':
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            | Problem | Description |
            |-|-|
            | [password-same-as-existing]() | New password cannot be same as existing password |
            | [password-does-not-meet-requirements]() | Password is weaker than allowed by password strength policy|
        default:
          $ref: '#/responses/default-error-response'

      tags:
        - Credentials
      x-asee-tags: []

  '/me/username':
    put:
      summary: Change username for authenticated user
      description: Sets new username for authenticated user. Username cannot be in use by other user
      operationId: Users_ChangeUsername
      parameters:
        - description: Command contains parameters for change of username.
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/change-username-command'
      responses:
        '204':
          description: No content - Username changed
        '440':
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            | Problem | Description |
            |-|-|
            | [username-already-used]() | Username {username} is already used |
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Credentials
      x-asee-tags: []

  '/me/email':
    put:
      summary: Register new email address
      description: Sets new or changes existing email in user profile and initates email verification process. Email cannot be in use by other user. Unverified email will be removed after period set by policy.
      operationId: Users_ChangeEmail
      parameters:
        - description: Command with parameters for new email
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/register-email-command'
      responses:
        '202':
          description: Accepted - Email verification kicked off
        '440':
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            | Problem | Description |
            |-|-|
            | [email-already-used]() | Email address {email} is already used |
        default:
          $ref: '#/responses/default-error-response'

      tags:
        - Users
      x-asee-tags: []

  '/me/email/confirm':
    put:
      summary: Confirm new email address for authenticated user
      description: Confirms users control of new email address based on OTP that was sent over email. This completes email verification process.
      operationId: Users_VerifyEmail
      parameters:
        - description: Command with parameters to confirm email address
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/confirm-email-command'
      responses:
        '204':
          description: No content - Email confirmed
        '440':
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            | Problem | Description |
            |-|-|
            | [verification-expired]() | Time allowed for verfication has expired  |

        default:
          $ref: '#/responses/default-error-response'

      tags:
        - Users
      x-asee-tags: []

  '/me/phone-number':
    put:
      summary: Register new phone number for authenticated user
      description: Sets new or changes exising phone number in user profile and initiates phone number verification process. Phone number cannot be in use by other user. Unverified phone numbers will be removed after period set by policy.
      operationId: Users_ChangePhoneNumber
      parameters:
        - description: Command with parameters for changing phone number
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/register-phone-number-command'
      responses:
        '202':
          description: Accepted - Phone number verification initiated
        '440':
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            | Problem | Description |
            |-|-|
            | [phone-number-already-used]() | Phone number {phone} is already used |
        default:
          $ref: '#/responses/default-error-response'

      tags:
        - Users
      x-asee-tags: []

  '/me/phone-number/confirm':
    put:
      summary: Confirm new phone number for authenticated user
      description: Confirms users control of new phone number based on OTP sent over SMS
      operationId: Users_ConfirmPhoneNumber
      parameters:
        - description: Command with parameters to confirm phone number
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/confirm-phone-number-command'
      responses:
        '204':
          description: No content - Phone number confirmed
        '440':
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            | Problem | Description |
            |-|-|
            | [verification-expired]() | Time allowed for verfication has expired  |
        default:
          $ref: '#/responses/default-error-response'

      tags:
        - Users
      x-asee-tags: []

  '/me/answers':
    put:
      summary: Set answers to security questions for authenticated user
      description: Sets answers for questeions which user has selected to be used for authentication in case of forgotten username or password
      operationId: Users_SetSecurityAnswers
      parameters:
        - description: Command with parameters to set security answers
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/set-security-answers-command'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/security-question-list'
        default:
          $ref: '#/responses/default-error-response'

      tags:
        - Credentials
      x-asee-tags: []

  '/users/{username}/password/reset':
    post:
      summary: Reset password for user
      description: Resets user password by randomly generating new one and initiates password reset process
      operationId: Users_ResetPassword
      parameters:
        - $ref: '#/parameters/username-param'
        - description: Command with parameters for password reset
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/initiate-password-reset-command'
      responses:
        '204':
          description: No content - Password reset process initiated
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Credentials
      x-asee-tags: []

  '/users':
    get:
      summary: Find user
      description:  "Finds user profile matching email, linked login, phone or customer number. All supplied parameters are matched against user repository. Parameters are optional but at least one parameter must be supplied. If more than one user profile matches supplied criteria `404 Not found` will be returned."
      operationId: Users_Find
      parameters:
        - $ref: '#/parameters/email-param'
        - $ref: '#/parameters/phone-number-param'
        - $ref: '#/parameters/customer-number-param'
        - $ref: '#/parameters/linked-login-param'
        - $ref: '#/parameters/include-param'
        - $ref: '#/parameters/trim-param'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/user'
        '404':
          description: Not found or multiple matches
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Users
      x-asee-tags: [Shapeable]
    post:
      summary: Register new user
      description: "Registers new user based on supplied profile details. Checks whether username, email, phone number are already used"
      operationId: Users_Register
      parameters:
        - description: Command with details of new user
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/register-user-command'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/resource-created-result'
          headers:
            Location:
              type: string
              description: The URL of the newly registered user
        '440':
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            | Problem | Description |
            |-|-|
            | [username-already-used]() | Username {username} is already used |
            | [email-already-used]() | Email address {email} is already used |
            | [phone-number-already-used]() | Phone number {phone} is already used |
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Users
      x-asee-tags: []

  '/users/{username}':
    get:
      summary: Get profile of specific user
      description: Retrieves user profile information for specified user
      operationId: Users_Get
      parameters:
        - $ref: '#/parameters/username-param'
        - $ref: '#/parameters/include-param'
        - $ref: '#/parameters/trim-param'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/user'
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Users
      x-asee-tags: [Shapeable]

  '/users/{username}/username-recovery':
    post:
      summary: Recover forgotten username for specific user
      description: Initiates process to recover forgotten username
      operationId: Users_InitiateUsernameRecovery
      parameters:
        - description: Command with parameters to recover forgotten username
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/initiate-username-recovery-command'
        - $ref: '#/parameters/username-param'
      responses:
        '202':
          description: Accepted - Username recovery initiated
        default:
          $ref: '#/responses/default-error-response'

      tags:
        - Credentials
      x-asee-tags: []

  '/users/{username}/available':
    get:
      summary: Check if username is available
      operationId: Users_CheckUsernameAvailability
      parameters:
        - $ref: '#/parameters/username-param'
      responses:
        200:
          description: OK - Username is available
        410:
          description: Gone - Username is not available
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Credentials
      x-asee-tags: []

  '/users/{username}/profile-picture':
    put:
      summary: Set profile picture for specific user
      description: Sets the profile picture for specific user
      operationId: Users_SetProfilePicture
      parameters:
        - $ref: '#/parameters/username-param'
        - description: Command with parameters to set profile picture
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/set-profile-picture-command'
      responses:
        '204':
          description: No content
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Credentials
      x-asee-tags: []

  '/users/{username}/hint-picture':
    put:
      summary: Set hint picture for specific user
      description: Sets the hint picture for specific user
      operationId: Users_SetHintPicture
      parameters:
        - $ref: '#/parameters/username-param'
        - description: Command with parameters to set hint picture
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/set-hint-picture-command'
      responses:
        '204':
          description: No content
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Credentials
      x-asee-tags: []

  '/users/{username}/questions':
    get:
      summary: Gets security questions
      description: Gets the security questions which user has selected to be used for identification and password change in case of forgotten password.
      operationId: Users_GetSecurityQuestions
      parameters:
        - $ref: '#/parameters/username-param'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/security-question-list'
        default:
          $ref: '#/responses/default-error-response'

      tags:
        - Credentials
      x-asee-tags: []

  '/users/{username}/answers/validate':
    post:
      summary: Validate answers on security questions
      operationId: Users_ValidateAnswers
      parameters:
        - description: Security answer validation request
          in: body
          name: req
          required: true
          schema:
            $ref: '#/definitions/validate-security-answers-request'
        - $ref: '#/parameters/username-param'
      responses:
        '200':
          description: OK - Answers are valid
        '440':
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            | Problem | Description |
            |-|-|
            | [answers-not-valid]() | Supplied answers to security questions are not valid |
          schema:
            $ref: '#/definitions/business-problem'
        default:
          $ref: '#/responses/default-error-response'
      tags:
        - Credentials
      x-asee-tags: []

parameters:
  include-param:
    description: List of fields to include in response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)
    in: query
    name: include
    type: array
    items:
      type: string
    collectionFormat: csv
    x-asee-common: true
  trim-param:
    description: List of fields to trim from response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)
    in: query
    name: trim
    type: array
    items:
      type: string
    collectionFormat: csv
    x-asee-common: true

  username-param:
    description: The username. Username is unique identifier
    in: path
    name: username
    required: true
    type: string

  email-param:
    description: The username. Username is unique identifier
    in: query
    name: email
    required: false
    type: string
    format: email

  phone-number-param:
    description: The username. Username is unique identifier
    in: query
    name: phone-number
    required: false
    type: string
    format: phone-number

  customer-number-param:
    description: The username. Username is unique identifier
    in: query
    name: customer
    required: false
    type: string

  linked-login-param:
    description: The username. Username is unique identifier
    in: query
    name: login
    required: false
    type: string

definitions:
  resource-created-result:
    description: Identifier of created resource
    type: string

  business-problem:
    description: Details on specific problem that prevented processing after successfull validation

    properties:
      problem:
        description: Unique literal that identifies specific problem
        type: string
      message:
        description: Message explaining the situation and optionaly remedies
        type: string
      details:
        description: Optional details supplied for troubleshooting
        type: string
    example:
      problem: document-locked
      message: Document you are trying to access is locked by another user
      details: User john.doe has locked the document

  password-requirements:
    description: Contains parameters for adding new external login provider
    properties:
      length:
        description: Minimum length of the password
        type: integer
        format: int32
      non-alphanumeric:
        type: boolean
        description: "A flag indicating if passwords must contain a non-alphanumeric character"
      lowercase:
        type: boolean
        description: A flag indicating if passwords must contain a lower case ASCII character
      uppercase:
        type: boolean
        description: A flag indicating if passwords must contain a upper case ASCII character
      digit:
        type: boolean
        description: A flag indicating if passwords must contain a digit
    example:
      length: 10
      non-alphanumeric: true
      lowercase: true
      uppercase: false
      digit: false

  register-linked-login-command:
    description: Contains parameters for adding new external login provider
    example:
      code: FB123456
      provider: Facebook
      redirect-uri: https://api.asse.com/external-login
    properties:
      code:
        description: Authentication code for third party provider.
        type: string
      provider:
        description: Name of the third party login provider.
        type: string
      redirect-uri:
        description: Uri of the third party login provider.
        type: string
    required:
      - code
      - provider


  change-password-command:
    description: Contains parameters for changing user's password.
    example:
      old-password: Test.User.1
      new-password: Test.User.2
    properties:
      old-password:
        description: Old password.
        type: string
      new-password:
        description: New password.
        type: string
    required:
      - old-password
      - new-password


  initiate-password-reset-command:
    description: Contains parameters for reset of user's password.
    example:
      username: test.user
      new-password: Test.User.2
    properties:
      username:
        x-asee-compliance: Do we need this property here or should it be part of the operation path
        description: Username.
        type: string
    required:
      - username


  change-username-command:
    description: Contains parameters for changing username
    example:
      username: test.user
    properties:
      new-username:
        description: Username
        type: string
    required:
      - new-username

  initiate-username-recovery-command:
    description: Contains parameters for username recovery
    example:
      username: test.user
    properties:
      username:
        description: Username to recover
        type: string
    required:
      - username

  register-email-command:
    description: Contains parameters for changing email address
    example:
      email: test.user@asse.com
    properties:
      new-email:
        description: New email to register
        type: string
        format: email
    required:
      - new-email

  confirm-email-command:
    description: Contains parameters for changing email address
    example:
      email: test.user@asse.com
    properties:
      username:
        description: Username whose email is being confirmed
        type: string
      email:
        description: Email to confirm
        type: string
        format: email
      confirmation-code:
        description: Code that will be used for confirmation
        type: string
    required:
      - email
      - confirmation-code

  confirm-phone-number-command:
    description: Contains parameters for changing phone number
    properties:
      username:
        description: Username whose email is being confirmed
        type: string
      phone-number:
        description: Phone number to confirm
        type: string
        format: phone
      confirmation-code:
        description: Code that will be used for confirmation
        type: string
    required:
      - phone-number
      - confirmation-code

  register-phone-number-command:
    description: Contains parameters for changing phone number
    example:
      phone-number: "381634323876"
    properties:
      new-phone-number:
        description: New phone number to register
        type: string
        format: phone
    required:
      - new-phone-number


  set-hint-picture-command:
    description: Contains parameters for setting new hint picture for the user
    example:
      url: https://api.asee.com/Picture1.jpg
    properties:
      url:
        description: URL of the hint picture.
        type: string
        format: url

  set-profile-picture-command:
    description: Contains parameters for setting new profile picture for the user
    example:
      url: https://api.asee.com/Picture1.jpg
    properties:
      url:
        description: URL of the profile picture.
        type: string
        format: url

  security-question-list:
    description: Security questions
    properties:
      questions:
        description: List of security questions.
        items:
          $ref: '#/definitions/security-question'
        type: array
    example:
      - question-id: "13424"
        question: What is your pet's name?
        description: Provide an answer about your pet's name
        answer-format-type: AnswerFormatType1
        answer-format: AnswerFormat1
        available-answers:
          - value: Value1
            text: Text1
      - question-id: "121324"
        question: What is your first teachers name?
        description: Description2
        answer-format-type: AnswerFormatType2
        answer-format: AnswerFormat2
        available-answers:
          - value: Value2
            text: Text2


  security-question:
    description: 'Security question'
    example:
      question-id: QuestionId
      question: Question
      description: Description
      answer-format-type: AnswerFormatType
      answer-format: AnswerFormat
      available-answers:
        - value: Value
          text: Text
    properties:
      question-id:
        description: Question identifier
        type: string
      question:
        description: Question text
        type: string
      description:
        description: Description
        type: string
      answer-format-type:
        x-asee-compliance: This property should be related to enumeration.
        description: Type of the answer format.
        type: string
      answer-format:
        x-asee-compliance: Is this also related to some enum?
        description: Answer format
        type: string
      available-answers:
        description: List of possible values for the answers.
        items:
          $ref: '#/definitions/available-answer'
        type: array


  available-answer:
    description: Possible value for the answer.
    example:
      value: Value
      text: Text
    properties:
      value:
        description: Answer value
        type: string
      text:
        description: Answer text
        type: string


  validate-security-answers-request:
    description: Contains list of answers to security questions that should be validated
    properties:
      answers:
        description: List of answers on security questions
        items:
          $ref: '#/definitions/security-answer'
        type: array


  set-security-answers-command:
    description: Contains list of answers to security questions
    properties:
      answers:
        description: List of answers on security questions
        items:
          $ref: '#/definitions/security-answer'
        type: array

  security-answer:
    description: Answer to security question.
    example:
      question-id: "75"
      answer: Blue
    properties:
      question-id:
        description: Question identifier.
        type: string
      answer:
        description: Answer to security question.
        type: string


  register-user-command:
    description: Contains parameters for regitration of new user
    example:
      customer-number: "2012034"
      first-name: Test User
      last-name: Test
      username: test.user
      password: Test.Password
      email: test.user@asse.com
      phone-number: "0569963512"
      hint-picture-url: /v1/content/hub/documents/7dkEiu883ks
    properties:
      customer-number:
        description: Unique customer identifier. Used for registering user who is already customer of the bank.
        type: string
      first-name:
        description: User's first name.
        type: string
      last-name:
        description: User's last name.
        type: string
      username:
        description: Username chosen by the user.
        type: string
      password:
        description: Password chosen by the user.
        type: string
      email:
        description: User's e-mail address.
        type: string
      phone-number:
        description: User's mobile phone number (capable of receiving SMS).
        type: string
      hint-picture-url:
        description: Picture that user has chosen to be used in login process as security measure against phishing attacks.
        type: string
    required:
      - username
      - password
      - email
      - phone-number


  user:
    description: Provides user information.
    example:
      last-login-on: '2016-01-01T00:00:00'
      name: TestUser
      customer-id: "2012034"
      email: testuser@asee.com
      username: test.user
      phone-number: "0569963512"
      external-login-providers:
        - facebook
      status: active
    properties:
      user-id:
        description: Unique id of user in identity store
        type: string
      username:
        description: Username chosen by the user
        type: string
      customer-number:
        description: "Unique identifier of customer in bank's records. Available if the user is already customer of the bank"
        type: string
      last-login:
        description: Date and time of last login
        format: date-time
        type: string
      last-answer-validated:
        description: Last time when security answer vas validated
        format: date-time
        type: string
      last-password-reset:
        description: Date and time of last login
        format: date-time
        type: string
      lock-expires:
        description: Date and time when lock expires
        format: date-time
        type: string
      first-name:
        description: User's first name
        type: string
      last-name:
        description: User's last name
        type: string
      email:
        description: Email address
        type: string
      email-verified:
        type: boolean
        description: A flag indicating if email has been verified for the user
      phone-number:
        description: Phone number
        type: string
      phone-number-verified:
        type: boolean
        description: A flag indicating if phone number has been verified for the user
      hint-picture-url:
        description: Picture that user has chosen to be used in login process as security measure against phishing attacks.
        type: string
      profile-picture-url:
        description: Picture user has set as his profile picture (avatar).
        type: string        
      linked-logins:
        description: Linked logins from external identity providers such as Google, Facebook, Microsoft
        items:
          $ref: '#/definitions/linked-login'
        type: array
      multifactor-enabled:
        type: boolean
        description: A flag indicating if multifactor authentication is enabled for the user
      status:
        description: |
          Status
          For a list of possible values see [user-statuses](identity-classifications.html#user-statuses) enumeration.
        enum:
          - active
          - locked
        type: string
        x-asee-enumeration: user-statuses

  linked-login:
    description: Login from social provider
    properties:
      login:
        description: Login name at google or facebook user name
        type: string
      provider:
        description: Identity provider compatible with Oauth2 and OpenID Connect
        type: string

responses:
  default-error-response:
    description: 'Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)'