openapi: "3.0.3"
info:
  title: IONOS Cloud - IAM Identity Password Policies API
  description: |
    API for managing Password Policies.
  version: 1.0.0
servers:
- url: https://iam.ionos.com
tags:
- name: PasswordPolicy
  description: |
    A password policy describes a set of rules regarding passwords. Authorization is controlled via JWT.
    
    This tag groups all operations for passwordpolicy.
paths:
  /passwordpolicies:
    get:
      operationId: passwordpoliciesGet
      summary: Retrieve all PasswordPolicy
      security:
      - tokenAuth: []
      description: |
        This endpoint enables retrieving all PasswordPolicy using
        pagination and optional filters.
      parameters:
        - $ref: "#/components/parameters/effectivePolicy"
      tags:
        - PasswordPolicy
      responses:
        "200":
          description: |
            Returned all requested PasswordPolicy successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PasswordPolicyReadList"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
    post:
      operationId: passwordpoliciesPost
      summary: Create PasswordPolicy
      security:
      - tokenAuth: []
      tags:
        - PasswordPolicy
      description: |
        Creates a new PasswordPolicy.
        
        The full PasswordPolicy needs to be provided to create the object.
        Optional data will be filled with defaults or left empty.
      requestBody:
        description: PasswordPolicy to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PasswordPolicyCreate"
      responses:
        "201":
          description: PasswordPolicy successfully created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PasswordPolicyRead"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "415":
          $ref: '#/components/responses/UnsupportedMediaType'
        "422":
          $ref: '#/components/responses/UnprocessableEntity'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /passwordpolicies/{passwordPolicyId}:
    get:
      operationId: passwordpoliciesFindById
      summary: Retrieve PasswordPolicy
      security:
      - tokenAuth: []
      tags:
        - PasswordPolicy
      description: Returns the PasswordPolicy by ID.
      parameters:
        - name: passwordPolicyId
          in: path
          schema:
            type: string
            format: uuid
          example: 70323699-7c28-58e7-9e0c-ff644f6947a5
          required: true
          description: The ID (UUID) of the PasswordPolicy.
      responses:
        "200":
          description: Getting PasswordPolicy was successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PasswordPolicyRead"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
    put:
      operationId: passwordpoliciesPut
      summary: Ensure PasswordPolicy
      security:
      - tokenAuth: []
      tags:
        - PasswordPolicy
      description: |
        Ensures that the PasswordPolicy with the provided ID is created or modified.
        The full PasswordPolicy needs to be provided to ensure
        (either update or create) the PasswordPolicy. Non present data will
        only be filled with defaults or left empty, but not take
        previous values into consideration.
      parameters:
        - name: passwordPolicyId
          in: path
          schema:
            type: string
            format: uuid
          example: 70323699-7c28-58e7-9e0c-ff644f6947a5
          required: true
          description: The ID (UUID) of the PasswordPolicy.
      requestBody:
        description: update PasswordPolicy
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PasswordPolicyEnsure"
      responses:
        "200":
          description: PasswordPolicy successfully updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PasswordPolicyRead"
        "201":
          description: PasswordPolicy successfully ensured.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PasswordPolicyRead"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "409":
          $ref: '#/components/responses/Conflict'
        "404":
          $ref: '#/components/responses/NotFound'
        "415":
          $ref: '#/components/responses/UnsupportedMediaType'
        "422":
          $ref: '#/components/responses/UnprocessableEntity'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
    delete:
      operationId: passwordpoliciesDelete
      summary: Delete PasswordPolicy
      security:
      - tokenAuth: []
      tags:
        - PasswordPolicy
      description: Deletes the specified PasswordPolicy.
      parameters:
        - name: passwordPolicyId
          in: path
          schema:
            type: string
            format: uuid
          example: 70323699-7c28-58e7-9e0c-ff644f6947a5
          required: true
          description: The ID (UUID) of the PasswordPolicy.
      responses:
        "202":
          description: Deleting PasswordPolicy was successful.
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
components:
  parameters:
    effectivePolicy:
      name: "effectivePolicy"
      in: query
      description: |
        When set to `true`, then the policy that is in effect for the actor's contract (as defined by the JWT) is returned.
        ATM this has the only effect that if no policy is defined for the user/contract, then the IONOS default policy is returned.
      required: false
      example: false
      schema:
        type: boolean
  schemas:
    PasswordPolicyReadList:
      allOf:
      - type: object
        required:
        - id
        - type
        - href
        properties:
          id:
            description: ID of the list of PasswordPolicy resources.
            type: string
            format: uuid
            example: 95f76a5e-86cd-52e0-b080-f22f131718e5
          type:
            description: The type of the resource.
            type: string
            enum:
            - collection
          href:
            description: The URL of the list of PasswordPolicy resources.
            type: string
            example: /passwordpolicies
          items:
            description: The list of PasswordPolicy resources.
            type: array
            items:
              $ref: '#/components/schemas/PasswordPolicyRead'
    PasswordPolicyRead:
      type: object
      required:
      - id
      - type
      - href
      - metadata
      - properties
      properties:
        id:
          type: string
          description: The ID (UUID) of the PasswordPolicy.
          format: uuid
          example: 70323699-7c28-58e7-9e0c-ff644f6947a5
        type:
          description: The type of the resource.
          type: string
          enum:
          - passwordpolicy
        href:
          description: The URL of the PasswordPolicy.
          type: string
          example: /passwordpolicies/70323699-7c28-58e7-9e0c-ff644f6947a5
        metadata:
          $ref: '#/components/schemas/Metadata'
        properties:
          $ref: '#/components/schemas/PasswordPolicy'
    PasswordPolicyEnsure:
      type: object
      required:
      - id
      - properties
      properties:
        id:
          type: string
          description: The ID (UUID) of the PasswordPolicy.
          format: uuid
          example: 70323699-7c28-58e7-9e0c-ff644f6947a5
        metadata:
          description: Metadata
          additionalProperties: true
          example: {}
        properties:
          $ref: '#/components/schemas/PasswordPolicy'
    PasswordPolicyCreate:
      type: object
      required:
      - properties
      properties:
        metadata:
          description: Metadata
          additionalProperties: true
          example: {}
        properties:
          $ref: '#/components/schemas/PasswordPolicy'
    PasswordPolicy:
      type: object
      required:
      - description
      - minLength
      properties:
        description:
          type: string
          description: Human readable description of the policy.
          maxLength: 1024
          example: "Password policy for John Doe."
        minLength:
          description: "Minimum number characters"
          minimum: 5
          type: integer
        minNumberChars:
          description: "Lower characters are considered to be all in range of [0-9]"
          type: integer
          default: 0
          minimum: 0
        minUpperChars:
          description: "Lower characters are considered to be all in range of [A-Z]"
          type: integer
          default: 0
          minimum: 0
        minLowerChars:
          description: "Lower characters are considered to be all in range of [a-z]"
          type: integer
          default: 0
          minimum: 0
        minSpecialChars:
          description: "Special characters are considered to be all characters that are not in the ASCII ranges [a-zA-Z0-9]"
          type: integer
          default: 0
          minimum: 0
    Error:
      description: |
        The Error object is used to represent an error response from the API.
      type: object
      properties:
        httpStatus:
          type: integer
          description: The HTTP status code of the operation.
          example: 400
        messages:
          type: array
          description: |
            A list of error messages.
          items:
            type: object
            properties:
              errorCode:
                type: string
                description: |
                  Application internal error code
                example: "err-1234"
              message:
                type: string
                description: |
                  A human readable explanation specific to this occurrence of the
                  problem.
                example: "Error message example"
    Metadata:
      type: object
      description: Metadata of the resource.
      properties:
        createdDate:
          type: string
          format: date-time
          description: The ISO 8601 creation timestamp.
          example: "2020-12-10T13:37:50+01:00"
          readOnly: true
        createdBy:
          type: string
          description: Unique name of the identity that created the resource.
          example: "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3"
          readOnly: true
        createdByUserId:
          type: string
          description: Unique id of the identity that created the resource.
          example: 87f9a82e-b28d-49ed-9d04-fba2c0459cd3
          readOnly: true
        lastModifiedDate:
          type: string
          format: date-time
          description: The ISO 8601 modified timestamp.
          example: "2020-12-11T13:37:50+01:00"
          readOnly: true
        lastModifiedBy:
          type: string
          description: Unique name of the identity that last modified the resource.
          example: "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3"
          readOnly: true
        lastModifiedByUserId:
          type: string
          description: Unique id of the identity that last modified the resource.
          example: 87f9a82e-b28d-49ed-9d04-fba2c0459cd3
          readOnly: true
        resourceURN:
          type: string
          description: Unique name of the resource.
          example: "ionos:<product>:<location>:<contract>:<resource-path>"
          readOnly: true
    Pagination:
      required:
      - offset
      - limit
      - _links
      description: |
        Pagination information. The offset and limit parameters are used to
        navigate the list of elements. The _links object contains URLs to
        navigate the different pages.
      type: object
      properties:
        offset:
          $ref: '#/components/schemas/Offset'
        limit:
          $ref: '#/components/schemas/Limit'
        _links:
          $ref: '#/components/schemas/Links'
    
    Offset:
      description: |
        The offset specified in the request (if none was specified, the default
        offset is 0).
      type: integer
      example: 0
      minimum: 0
      readOnly: true
    Limit:
      description: |
        The limit specified in the request (if none was specified, use the
        endpoint's default pagination limit).
      type: integer
      example: 42
      minimum: 0
      readOnly: true
    Links:
      description: |
        URLs to navigate the different pages. As of now we always only return a
        single page.
      type: object
      properties:
        prev:
          description: |
            URL (with offset and limit parameters) of the previous page; only
            present if offset is greater than 0.
          type: string
          format: uri
          example: http://PREVIOUS-PAGE-URI
          readOnly: true
        self:
          description: |
            URL (with offset and limit parameters) of the current page.
          type: string
          format: uri
          example: http://THIS-PAGE-URI
          readOnly: true
        next:
          description: |
            URL (with offset and limit parameters) of the next page; only
            present if offset + limit is less than the total number of elements.
          type: string
          format: uri
          example: http://NEXT-PAGE-URI
          readOnly: true
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        The token can be generated using the 
        [Authentication API](https://api.ionos.com/docs/authentication/v1/#tag/tokens/operation/tokensGenerate).
  responses:
    BadRequest:
      description: |
        ### Bad Request
        The request send to the API was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: |
        ### Unauthorized
        The request is missing authorization information or the authorization information provided are expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotAllowed:
      description: |
        ### Not Allowed
        The user issuing the request does not have the needed permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: |
        ### Conflict
        The UUID is already taken by another party, follow the guides to generate UUIDs uniquely.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: |
        ### Not Found
        The resource that was requested could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnexpectedError:
      description: |
        ### Unexpected Internal Server Error
        An unexpected internal error occurred. We apologize for the inconvenience!
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: |
        ### Unprocessable Entity
        The request was well-formed but was unable to be followed due to semantic errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: |
        ### Too Many Requests
        The user has sent too many requests in a given amount of time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: |
        ### Unsupported Media Type
        The request has an unsupported media type.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: |
        ### Internal Server Error
        An internal error occurred. We apologize for the inconvenience!
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: |
        ### Service Unavailable
        The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
