

# API spec in YAML
swagger: '2.0'
info:
  title: wetransform.to User Service
  description: Login and user management
  version: "1.0.0"
# the domain of the service
host: haleconnect.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /accounts/v1
produces:
  - application/json
paths:
  /config:
    get:
      summary: Service configuration information
      description: Provides information about the service configuration and capabilities.
      produces:
        - application/json
      tags:
        - Configuration
      responses:
        200:
          description: Configuration information
          schema:
            type: object
          examples:
            application/json: |-
              {
                "adminEmail": "admin@wetransform.to",
                "signupEnabled": true,
                "loginEnabled": true,
                "password": {
                  "signup": true,
                  "login": true,
                  "loginWithEmail": true
                },
                "oauth": {
                  "linkedin": true,
                  "google": true
                }
              }
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  /roles:
    get:
      summary: User roles
      description: Provides information about the different user roles defined in the platform.
      produces:
        - application/json
      tags:
        - Configuration
      responses:
        200:
          description: Role definitions
          schema:
            type: object
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  /profile:
    get:
      summary: Profile of the logged in user
      description: Returns the profile of the user authenticated with the user service.
      tags:
        - Users
      responses:
        200:
          description: Profile information for a user
          schema:
            $ref: '#/definitions/User'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/names/user/propose/{name}':
    get:
      summary: Get a valid available screen name proposal
      description: Get a valid available screen name proposal based on the provided name
      tags:
        - Users
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/name'
      responses:
        200:
          description: Valid name could be determined
          schema:
            type: object
            required:
              - name
            properties:
              name:
                type: string
        409:
          description: If no available screen name could be determined
          schema:
            $ref: '#/definitions/Feedback'

  '/tokens/{tokenType}/{token}':
    get:
      summary: Determines the validity of a token
      description: Determines if a token is valid, dependending on the type of token passed
      tags:
        - Tokens
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/tokenType'
        - $ref: '#/parameters/token'
      responses:
        200:
          description: Provided token is valid
          schema:
            $ref: '#/definitions/Feedback'
        400:
          description: Provided token or tokenType is invalid
          schema:
            $ref: '#/definitions/Feedback'



  '/names/org/propose/{name}':
    get:
      summary: Get a valid available URL name proposal
      description: Get a valid available URL name proposal based on the provided name
      tags:
        - Organisations
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/name'
      responses:
        200:
          description: Valid name could be determined
          schema:
            type: object
            required:
              - name
            properties:
              name:
                type: string
        409:
          description: If no available URL name could be determined
          schema:
            $ref: '#/definitions/Feedback'

  /profile/password:
    put:
      summary: Change current user password
      description: Change the password of the user that is currently logged in.
      tags:
        - Users
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Current and new password
          required: true
          schema:
            type: object
            required:
              - current
              - new
            properties:
              current:
                type: string
                description: Current password
              new:
                type: string
                description: New password
      responses:
        200:
          description: Password changed
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error changing the password
          schema:
            $ref: '#/definitions/Feedback'

  /test/users:
    post:
      tags:
        - Users
      summary: Create a new user for test purposes
      description: Test users don't require activation and can only be created with admin access
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Information on user that should be created
          required: true
          schema:
            $ref: '#/definitions/NewTestUser'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/NewResourceInfo'
        default:
          description: Error creating the organisation
          schema:
            $ref: '#/definitions/Feedback'

  /users:
    post:
      tags:
        - Users
      summary: Create a new user
      description: ''
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Information on user that should be created
          required: true
          schema:
            $ref: '#/definitions/NewUser'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/NewResourceInfo'
        default:
          description: Error creating the organisation
          schema:
            $ref: '#/definitions/Feedback'
    get:
      tags:
        - Users
      summary: Find users
      description: Find users based on the current user context
      parameters:
        - $ref: '#/parameters/context'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/UserInfo'
        default:
          description: Error accessing organisations
          schema:
            $ref: '#/definitions/Feedback'

  '/users/{user}':
    get:
      summary: User profile
      description: Returns the public profile of a specific user.
      tags:
        - Users
      parameters:
        - $ref: '#/parameters/userIdent'
      responses:
        200:
          description: Profile information for a user
          schema:
            $ref: '#/definitions/User'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Delete user
      description: Delete the user
      tags:
        - Users
      parameters:
        - $ref: '#/parameters/userId'
      responses:
        200:
          description: User was deleted
          schema:
            $ref: '#/definitions/Feedback'
        404:
          description: User was not found
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/users/{user}/info':
    get:
      summary: User information
      description: Returns the information about a specific user.
      tags:
        - Users
      parameters:
        - $ref: '#/parameters/userIdent'
      responses:
        200:
          description: Information for a user
          schema:
            $ref: '#/definitions/UserLimitedInfo'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'          

  '/users/{user}/{name}':
    put:
      summary: Set a specific user information
      tags:
        - Users
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/userIdent'
        - $ref: '#/parameters/propertyName'
        - $ref: '#/parameters/propertyValue'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Delete a specific user information
      tags:
        - Users
      parameters:
        - $ref: '#/parameters/userIdent'
        - $ref: '#/parameters/propertyName'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/users/{user}/p/{name}':
    put:
      summary: Set a generic user property
      tags:
        - Users
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/userIdent'
        - $ref: '#/parameters/propertyName'
        - $ref: '#/parameters/propertyValue'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Delete a generic user property
      tags:
        - Users
      parameters:
        - $ref: '#/parameters/userIdent'
        - $ref: '#/parameters/propertyName'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/users/{user}/sp/{name}':
    get:
      summary: Get a secret user property
      tags:
        - Users
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/userIdent'
        - $ref: '#/parameters/propertyName'
      responses:
        200:
          description: Returns property map for value
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    put:
      summary: Set a secret user property
      tags:
        - Users
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/userIdent'
        - $ref: '#/parameters/propertyName'
        - $ref: '#/parameters/propertyValue'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Delete a secret user property
      tags:
        - Users
      parameters:
        - $ref: '#/parameters/userIdent'
        - $ref: '#/parameters/propertyName'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/users/{user}/new/activationmail':
    get:
      summary: Resends the activation email
      tags:
        - Users
      parameters:
        - $ref: '#/parameters/userIdent'
      responses:
        200:
          description: New activation email has been sent
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error sending new activation email
          schema:
            $ref: '#/definitions/Feedback'
            

  '/users/{user}/new/email':
    post:
      summary: Send an email to a user
      tags:
        - Users
      parameters:
        - $ref: '#/parameters/userIdent'
        - $ref: '#/parameters/emailParams'
      responses:
        200:
          description: The email has been sent
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error sending the email
          schema:
            $ref: '#/definitions/Feedback'

  '/users/{user}/addDemoDays':
    put:
      summary: Add days to user's demo period
      description: Add days to user's demo period
      tags:
        - Users
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/userIdent'
        - name: days
          in: body
          type: string
          required: true
      responses:
        200:
          description: Days added

  /reset:
    post:
      summary: Initiate a password reset for a user
      tags:
        - Users
      parameters:
        - name: body
          in: body
          required: true
          description: Identifies the user to reset the password for
          schema:
            type: object
            properties:
              email:
                type: string
                description: The user's email address
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        403:
          description: Resetting the password is not allowed, e.g. because a password reset is still in progress or a password reset was canceled recently
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/reset/{token}':
    put:
      summary: Reset a user's password
      tags:
        - Users
      parameters:
        - name: token
          in: path
          description: Reset token
          type: string
          required: true
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              password:
                type: string
                description: The new password to set for the user
      responses:
        200:
          description: The user's password was reset successfully
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Resetting the password failed
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Cancel resetting a password
      tags:
        - Users
      parameters:
        - name: token
          in: path
          description: Reset token
          type: string
          required: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
            
  '/features/{org}':
    put:
      summary: Set the dynamic feature toggle configuration for an organisation
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
        - in: body
          name: body
          description: Array with toggle configurations
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/FeatureToggleValue'
      responses:
        200:
          description: The feature toggle configuration was saved successfully
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Resetting the password failed
          schema:
            $ref: '#/definitions/Feedback'
    get:
      summary: Get the dynamic feature toggle configuration for an organisation
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/FeatureToggleValue'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  /auth/login:
    post:
      summary: Login with username
      description: Login using username and password
      tags:
        - Login
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          description: User credentials
          schema:
            $ref: '#/definitions/Credentials'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Token'
        default:
          description: Wrong credentials
          schema:
            $ref: '#/definitions/Feedback'

  /auth/oidc:
    post:
      summary: Login with OIDC
      description: Login or register using OpenID Connect access token
      tags:
        - Login
        - Register
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          description: Access token and provider ID
          schema:
            $ref: '#/definitions/OidcAuthRequest'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Token'
        default:
          description: Wrong credentials
          schema:
            $ref: '#/definitions/Feedback'

  /auth/logout:
    post:
      summary: Logs a user out of the system
      description: Logs a user out of the system
      tags:
        - Login
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          # Swagger requires a body to be present for POST requests even if it's not used.
          #Otherwise the operation fails
          description: Stub body
          schema:
            type: object
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Invalid auth token
          schema:
            $ref: '#/definitions/Feedback'

  /auth/validate:
    get:
      summary: Validates an authentication token
      description: Validates an authentication token
      tags:
        - Login
      responses:
        200:
          description: The token is valid
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Invalid auth token
          schema:
            $ref: '#/definitions/Feedback'

  /auth/signup:
    post:
      summary: Create a new user
      description: Create a new user pending activation
      tags:
        - Register
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          description: The sign up information
          schema:
            $ref: '#/definitions/SignUpInfo'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Wrong credentials
          schema:
            $ref: '#/definitions/Feedback'

  /auth/signup/newsletter:
    post:
      summary: Create a new user with option to subscribe to newsletter
      description: Create a new user with option to subscribe to newsletter pending activation
      tags:
        - Register
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          description: The sign up information
          schema:
            $ref: '#/definitions/SignUpInfo'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Wrong credentials
          schema:
            $ref: '#/definitions/Feedback'



  /migration/startDemo/{user}:
    put:
      summary: Starts a given users time as a demo user
      description: Starts a given users time as a demo user
      tags:
        - Migration
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/userIdent'
        - name: orgId
          in: body
          type: string
          required: true
      responses:
        200:
          description: User role changed successfully
        default:
          description: Wrong credentials

  /auth/google:
    post:
      summary: Login with Google
      description: Use Google to login via OAuth 2.0
      tags:
        - OAuth
        - Login
        - Register
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/AuthRequest'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Token'
        default:
          description: Error during authentication
          schema:
            $ref: '#/definitions/Feedback'

  /auth/linkedin:
    post:
      summary: Login with LinkedIn
      description: Use LinkedIn to login via OAuth 2.0
      tags:
        - OAuth
        - Login
        - Register
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/AuthRequest'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Token'
        default:
          description: Error during authentication
          schema:
            $ref: '#/definitions/Feedback'

  '/activate/{token}':
    get:
      summary: Activate a self-registered account
      tags:
        - Register
      parameters:
        - name: token
          in: path
          type: string
          required: true
      responses:
        200:
          description: Account was activated
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error during activation
          schema:
            $ref: '#/definitions/Feedback'
    put:
      summary: Activate an account
      tags:
        - Register
      consumes:
        - application/json
      parameters:
        - name: token
          in: path
          type: string
          required: true
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/ActivationOptions'
      responses:
        200:
          description: Account was activated
          schema:
            $ref: '#/definitions/Token'
        default:
          description: Error during activation
          schema:
            $ref: '#/definitions/Feedback'

  '/activate/newsletter/{token}':
    put:
      summary: Activate an account and subscribe it to the newsletter
      tags:
        - Register
      consumes:
        - application/json
      parameters:
        - name: token
          in: path
          type: string
          required: true
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/ActivationOptions'
      responses:
        200:
          description: Account was activated and subscribed to the newsletter
          schema:
            $ref: '#/definitions/Token'
        default:
          description: Error during activation
          schema:
            $ref: '#/definitions/Feedback'


  '/confirm/{token}':
    get:
      summary: Confirm an email address for a user account
      tags:
        - Users
      parameters:
        - name: token
          in: path
          type: string
          required: true
      responses:
        200:
          description: Email address was confirmed
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error confirming email address
          schema:
            $ref: '#/definitions/Feedback'

  /orgs:
    post:
      tags:
        - Organisations
      summary: Create a new organisation
      description: ''
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Organisation that should be created
          required: true
          schema:
            $ref: '#/definitions/NewOrganisation'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/NewResourceInfo'
        default:
          description: Error creating the organisation
          schema:
            $ref: '#/definitions/Feedback'
      security:
        - bearer: []
    get:
      tags:
        - Organisations
      summary: Find organisations
      description: Find organisations based on the current user context
      parameters:
        - $ref: '#/parameters/context'
        - $ref: '#/parameters/includeParents'
      produces:
        - application/json
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/OrganisationInfo'
        default:
          description: Error accessing organisations
          schema:
            $ref: '#/definitions/Feedback'

  '/orgs/{org}':
    get:
      summary: Get information on a specific organisation
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
      responses:
        200:
          description: The organisation information
          schema:
            $ref: '#/definitions/Organisation'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Delete an organisation
      description: Delete an organisation. An organisation that has any sub-organisations cannot be deleted. Users that are members of the organisation loose the membership.
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/orgs/{org}/parents':
    get:
      summary: List the parent organisations for a specific organisation
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
      responses:
        200:
          description: The list of parent organisations identifiers
          schema:
            type: array
            items:
              type: string
            description: Identifiers of parent organisations on all hierarchy levels

        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/orgs/{org}/members':
    post:
      summary: Associate a user with an organisation
      tags:
        - Organisations
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/orgIdent'
        - in: body
          name: body
          description: User role assocation
          required: true
          schema:
            $ref: '#/definitions/RoleAssociation'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/orgs/{org}/invite':
    post:
      summary: Invite a user to be associated with an organisation
      tags:
        - Organisations
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/orgIdent'
        - in: body
          name: body
          description: User role assocation
          required: true
          schema:
            $ref: '#/definitions/RoleInvite'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/orgs/{org}/invite/accept':
    put:
      summary: Accept a user invite to an org
      tags:
        - Organisations
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/orgIdent'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/orgs/{org}/invite/decline':
    put:
      summary: Accept a user invite to an org
      tags:
        - Organisations
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/orgIdent'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'


  '/orgs/{org}/members/{user}':
    delete:
      summary: Remove a user from an organisation
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
        - $ref: '#/parameters/userIdent'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/orgs/{org}/p/{name}':
    put:
      summary: Set a generic organisation property
      tags:
        - Organisations
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/orgIdent'
        - $ref: '#/parameters/propertyName'
        - $ref: '#/parameters/propertyValue'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Remove a generic organisation property
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
        - $ref: '#/parameters/propertyName'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    get:
      summary: Get an organisation's generic property value
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
        - $ref: '#/parameters/propertyName'
        - $ref: '#/parameters/searchInherited'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/orgs/{org}/sp/{name}':
    get:
      summary: Get a generic organisation property
      tags:
        - Organisations
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/orgIdent'
        - $ref: '#/parameters/propertyName'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    put:
      summary: Set a generic organisation property
      tags:
        - Organisations
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/orgIdent'
        - $ref: '#/parameters/propertyName'
        - $ref: '#/parameters/propertyValue'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Remove a generic organisation property
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
        - $ref: '#/parameters/propertyName'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/orgs/{org}/{name}':
    put:
      summary: Set a specific organisation information
      tags:
        - Organisations
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/orgIdent'
        - $ref: '#/parameters/propertyName'
        - $ref: '#/parameters/propertyValue'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Remove a specific organisation information
      tags:
        - Organisations
      parameters:
        - $ref: '#/parameters/orgIdent'
        - $ref: '#/parameters/propertyName'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

# Permission related paths

  # XXX Referencing from other files does not seem to work in Swagger UI
  # (File is fetched, but operations do not appear)
  # /permissions/resource/{resourceType}/{permission}:
  #   $ref: 'permissions.yaml#/permissions/application/{permission}'
  # /permissions/resource/{resourceType}/{permission}:
  #   $ref: 'permissions.yaml#/permissions/application/{permission}'

  /permissions/resource/{resourceType}/{permission}:
    parameters:
      - $ref: '#/parameters/resourceType'
      - $ref: '#/parameters/permission'
    get:
      tags:
        - Permissions
      summary: Retrieve information on a specific resource permission for a user.
      description: |
        The permission is a permission for an action on a resource, e.g. *edit* a *User*.
      responses:
        200:
          $ref: '#/responses/permissionInformation'

  /permissions/application/{permission}:
    parameters:
      - $ref: '#/parameters/permission'
    get:
      tags:
        - Permissions
      summary: Retrieve information on an application permission for a user.
      description: |
        The permission is a permission for an action in an application.
      responses:
        200:
          $ref: '#/responses/permissionInformation'

            
  '/notifyadmin/email':
    post:
      summary: Sends an email to the system admin
      tags:
        - Admin
      parameters:
        - $ref: '#/parameters/emailParams'
      responses:
        200:
          description: Email has been sent to admin successfully
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error sending Email to admin
          schema:
            $ref: '#/definitions/Feedback'

  '/notifyserviceteam/email':
    post:
      summary: Sends an email to the service team
      tags:
        - Users
      parameters:
        - $ref: '#/parameters/emailParams'
      responses:
        200:
          description: Email has been sent to the service team successfully
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error sending Email to the service team
          schema:
            $ref: '#/definitions/Feedback'
            
  '/testmail/{emailPrefix}':
    get:
      summary: Sends one batch email to a set of generated internal email addresses
      tags:
        - Admin
      parameters:
        - $ref: '#/parameters/emailPrefix'
      responses:
        200:
          description: The batch email delivery was attempted (Service logs still have to be checked to see if it was successful)
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error attempting to send batch emails
          schema:
            $ref: '#/definitions/Feedback'  


  '/password/config':
    get:
      summary: Password strength configuration
      description: Returns information about the password strength criteria (lowercase, uppercase, etc). If the request initiator doesn't provide any credentials or cannot be determined, a default configuration gets returned
      tags:
        - Passwords
      responses:
        200:
          description: Password strength object for password chhange
          schema:
            $ref: '#/definitions/PasswordStrengthSettings'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/password/config/activate/{token}':
    get:
      summary: Password strength configuration for user activation
      description: Returns information about the password strength criteria (lowercase, uppercase, etc) specific to this request initiator by using an activate token. If the token is invalid or the request initiator cannot be determined, a default configuration gets returned
      tags:
        - Passwords
      parameters:
        - $ref: '#/parameters/token'
      responses:
        200:
          description: Password strength object
          schema:
            $ref: '#/definitions/PasswordStrengthSettings'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  '/password/config/reset/{token}':
    get:
      summary: Password strength configuration for password resetting
      description: Returns information about the password strength criteria (lowercase, uppercase, etc) specific to this request initiator by using a reset token. If the token is invalid or the request initiator cannot be determined, a default configuration gets returned
      tags:
        - Passwords
      parameters:
        - $ref: '#/parameters/token' 
      responses:
        200:
          description: Password strength object
          schema:
            $ref: '#/definitions/PasswordStrengthSettings'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'


# Security definitions

securityDefinitions:
  bearer:
    type: apiKey
    name: Authorization
    in: header

# Parameters

parameters:
  orgIdent:
    name: org
    in: path
    description: 'Organisation identifier, URL name or unique ID'
    required: true
    type: string
  propertyName:
    name: name
    in: path
    description: The name of the referenced property
    required: true
    type: string
  propertyValue:
    name: body
    in: body
    required: true
    description: Property value
    schema:
      type: string
  searchInherited:
    name: searchInherited
    in: query
    description: Whether or not search for a property among it's ancestor organisations
    required: false
    type: boolean
  includeParents:
    name: includeParents
    in: query
    description: Whether or not to include the parents of the current context's organisation when retrieving the organisation list
    required: false
    type: boolean
  userIdent:
    name: user
    in: path
    description: Screen name or user ID
    required: true
    type: string
  userId:
    name: user
    in: path
    description: User ID
    required: true
    type: integer
  context:
    name: WETF-Context-Organisation
    in: header
    description: The organisation context
    required: false
    type: string
  name:
    name: name
    in: path
    description: The suggested name
    required: true
    type: string
  emailParams:
    name: emailParams
    in: body
    description: The email parameters
    required: true
    schema:
      $ref: '#/definitions/EmailParams'

  # Permissions
  resourceType:
    name: resourceType
    description: Well-defined resource type name
    in: path
    type: string
    required: true
  permission:
    name: permission
    description: The resource or application permission name
    in: path
    type: string
    required: true

  token:
    name: token
    description: token that identifies a user that is not logged in yet
    in: path
    type: string
    required: true

  tokenType:
    name: tokenType
    description: type of operation that is being validated by the token
    in: path
    type: string
    enum:
      - reset
      - activation
      - email
    required: true

  emailPrefix:
    name: emailPrefix
    description: prefix (before the 'at') to generate internal test email addresses
    in: path
    type: string
    required: true

definitions:
  NewUser:
    type: object
    required:
      - email
    properties:
      screenName:
        type: string
        description: Screen name of the user
      fullName:
        type: string
        description: Full name of the user
      avatarUrl:
        type: string
        description: Image URL of the user
      aboutMe:
        type: string
        description: Free text about the user
      email:
        type: string
        description: The users email address
      p:
        type: object
        description: Object with generic user properties
      orgRoles:
        type: object
        description: Object mapping organisation IDs to role identifiers

  NewTestUser:
    allOf:
      - $ref: '#/definitions/NewUser'
      - type: object
        required:
          - password
        properties:
          password:
            type: string
            description: The password to set

  User:
    allOf:
      - $ref: '#/definitions/NewUser'
      - type: object
        required:
          - id
        properties:
          id:
            type: string
            description: Unique user identifier
          firstName:
            type: string
            description: First name of the user
          lastName:
            type: string
            description: Last name of the user

  UserInfo:
    type: object
    properties:
      id:
        type: string
        description: Unique user identifier
      screenName:
        type: string
        description: Screen name of the user
      firstName:
        type: string
        description: First name of the user
      lastName:
        type: string
        description: Last name of the user
      fullName:
        type: string
        description: Full name of the user
      avatarUrl:
        type: string
        description: Image URL of the user
      aboutMe:
        type: string
        description: Free text about the user
      enabled:
        type: boolean
        description: If the user is enabled
      activated:
        type: boolean
        description: If the user has activated the account
      orgRoles:
        type: object
        description: Object mapping organisation IDs to role identifiers

  UserLimitedInfo:
    type: object
    properties:
      fullName:
        type: string
        description: Full name of the user
      avatarUrl:
        type: string
        description: Image URL of the user

  NewResourceInfo:
    type: object
    required:
      - id
    properties:
      id:
        type: string
        description: Unique user identifier

  RoleInvite:
    type: object
    required:
      - username
      - role
    properties:
      username:
        type: string
        description: Unique user identifier
      role:
        type: string
        description: Role identifier

  RoleAssociation:
    type: object
    required:
      - userId
    properties:
      userId:
        type: string
        description: Unique user identifier
      role:
        type: string
        description: Role identifier

  NewOrganisation:
    type: object
    required:
      - name
    properties:
      urlName:
        type: string
        description: Identifying name of the organisation
      name:
        type: string
        description: The human readable organisation name
      parentOrg:
        type: string
        description: The identifier of the parent organisation
      contactEmail:
        type: string
        description: Email contact of the organisation
      avatarUrl:
        type: string
        description: Image URL of the organisation
      about:
        type: string
        description: Free text describing the organisation
      p:
        type: object
        description: Object with generic organisation properties

  Organisation:
    allOf:
      - $ref: '#/definitions/NewOrganisation'
      - type: object
        required:
          - id
        properties:
          id:
            type: string
            description: Unique organisation identifier
          subOrgs:
            type: array
            items:
              type: string
            description: Identifiers of sub-organisations on all hierarchy levels
          directSubOrgs:
            type: array
            items:
              type: string
            description: Identifiers of sub-organisations on the next hierarchy level

  OrganisationInfo:
    type: object
    required:
      - name
    properties:
      id:
        type: string
        description: Unique organisation identifier
      urlName:
        type: string
        description: Identifying name of the organisation
      name:
        type: string
        description: The human readable organisation name
      parentOrg:
        type: string
        description: The identifier of the parent organisation
      contactEmail:
        type: string
        description: Email contact of the organisation
      avatarUrl:
        type: string
        description: Image URL of the organisation
      about:
        type: string
        description: Free text describing the organisation
      subOrgs:
        type: array
        items:
          type: string
        description: Identifiers of sub-organisations on all hierarchy levels

#  PrivateProfile:
#    allOf:
#      - $ref: '#/definitions/PublicProfile'
#      - type: object
#        required:
#          - email
#        properties:
#          email:
#            type: string
#          hasPassword:
#            type: boolean
          # TODO: identities

  Credentials:
    properties:
      username:
        type: string
        description: The user name or ID
      password:
        type: string
        description: The (hashed) password of the user

  ActivationOptions:
    properties:
      password:
        type: string
        description: The password to set for the activated user
      # login:
      #   type: boolean
      #   description: If the user should be logged in after activation

  SignUpInfo:
    required:
      - email
    properties:
      email:
        type: string
        description: The user's email address
      fullName:
        type: string
        description: The user's full name
      screenName:
        type: string
        description: The user's desired screen name
      password:
        type: string
        description: The plain text password of the user
      avatarUrl:
        type: string
        description: Image URL of the user
      aboutMe:
        type: string
        description: Free text about the user
      p:
        type: object
        description: Generic user properties

  LegacyForumSignUpInfo:
    required:
      - email
      - fullName
      - legacyId
    properties:
      email:
        type: string
        description: The new user's email address
      fullName:
        type: string
        description: The new user's full name
      legacyId:
        type: integer
        description: The new user's ID that they had in the old forum

  FeatureToggleValue:
    required:
      - name
      - enabled
    properties:
      name:
        type: string
        description: The feature toggle's name
      enabled:
        type: boolean
        description: The new user's full name
        
  ExistentUserEmail:
    required:
      - email
    properties:
      email:
        type: string
        description: The new user's email address

  AuthRequest:
    properties:
      code:
        type: string
        description: The authorization code issued by the OAuth service provider
      clientId:
        type: string
        description: The applications client ID with the OAuth service provider
      redirectUri:
        type: string
        description: The redirect URI

  OidcAuthRequest:
    properties:
      accessToken:
        type: string
        description: The access token issued by the identity provider
      providerId:
        type: string
        description: The identifier of the identity provider in the platform

  Token:
    properties:
      token:
        type: string
        description: The authentication token

  Feedback:
    type: object
    required:
      - code
      - message
      - error
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      error:
        type: boolean

  EmailParams:
    type: object
    required:
      - subject
      - html
    properties:
      subject:
        type: string
      html:
        type: string


  PasswordStrengthSettings:
    type: object
    required:
      - minGroups
      - criteria
    properties:
      minGroups:
        type: integer
        description: Minimum number of complexity groups that should be met
      youngestReusablePassword:
        type: integer
        description: Number of previous passwords used by this user that cannot be reused
      criteria:
        type: object
        description: array of password strength criteria that should be met
        schema:
          $ref: '#/definitions/PasswordStrengthCriteriaArray'

  PasswordStrengthCriteriaArray:
    type: object
    description: array of password strength criteria that should be met
    required:
      - lowercase
      - numbers
      - minLength
      - specialCharacters
      - uppercase
    properties:
      lowercase:
        type: object
        description: Minimum number of lowercase characters that should be present on the password
        schema:
          $ref: '#/definitions/PasswordStrengthCriteriaEntry'
      numbers:
        type: object
        description: Minimum number of numeric characters that should be present on the password
        schema:
          $ref: '#/definitions/PasswordStrengthCriteriaEntry'
      minLength:
        type: object
        description: Minimum number of characters that should be present on the password
        schema:
          $ref: '#/definitions/PasswordStrengthCriteriaEntry'
      specialCharacters:
        type: object
        description: Minimum number of special characters (Non-alphanumeric) that should be present on the password
        schema:
          $ref: '#/definitions/PasswordStrengthCriteriaEntry'
      uppercase:
        type: object
        description: Minimum number of uppercase characters that should be present on the password
        schema:
          $ref: '#/definitions/PasswordStrengthCriteriaEntry'


  PasswordStrengthCriteriaEntry:
    type: object
    required:
      - expectedOccurrences
      - name
    properties:
      expectedOccurrences:
        type: integer
        description: Minimum number of occurences expected from this character type
      name:
        type: string
        description: Name of the criteria entry


# Response definitions
responses:
  # Permissions
  permissionInformation:
    description: |
      The response specifies for the requesting user's contexts (which may be the user context or any of his organisation roles), if or given which conditions he has the queried permission.
      For each context the permission information can be either `true`, `false` or an array of conditions.
      * `true` means that the permission is granted without condition,
      * `false` that it is denied and
      * the array contains the names of the conditions, only one condition must be met for the permission to be granted
    examples:
      application/json: |-
        {
          "user": false,
          "organisations": {
            "org1": true,
            "org2": false,
            "org3": ["organisations", "suborganisations"]
          }
        }
    schema:
      type: object
