openapi: 3.0.3
info:
  title: RITM API V2
  description: |-
    RITM is a delegated identity management system that allows organisations to securely connect identities through roles and their associated entitlements, while leveraging self-service capabilities.

    **Introduction to the RITM API**

    Next to technical API's that are typically used by the RITM platform itself, OneWelcome also provides more functional oriented API's to ease integrations with the customers' applications.
    This specification is meant to provide information and guidance with respect to the functional RITM API's.

    **Versions of the API**

    Our API's are versioned and will remain backwards-compatible for 6 months after the end-of-life for this particular version is announced. Newer versions are expected to be compatible with old versions but both request parameters and response bodies could be subject to changes between versions.

    The response body for an API call could contain more information then described in this specification and users of the API should ignore this extra information.

  termsOfService: https://www.onewelcome.com/terms-of-use
  license:
    name: OneWelcome License
    url: https://www.onewelcome.com/
  version: 2022.12.1
externalDocs:
  description: Find out more about RITM
  url: https://developer.onewelcome.com/documentation/introduction-to-ritm
servers:
  - url: https://{customerID}.iwelcome.com/api/v2
    description: customerID is assigned by OneWelcome
tags:
  - name: Data/Groups
    description: |-
      Calls related to the management of groups in structures.
paths:
  /group:
    post:
      tags:
        - Data/Groups
      summary: Create a new group
      description: |-
        Users with RITM Admin roles and with the correct platform access can create a new group using this API.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/groupCreateRequest"
            example:
              {
                "code": "test4",
                "name": "name for test 4",
                "structureCode": "structure-1234567891011",
                "groupParent": "test3",
                "attributes": {
                  "vatNumber": 63826383
                },
                "roles": [
                  {
                    "code": "role-673f20jvsklwh",
                    "type": "ACCESS"
                  },
                  {
                    "code": "role-63nso3bs9ln",
                    "type": "ADMIN"
                  }
                ]
              }
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: object
              example:
                {
                  "name": "name for test 4",
                  "code": "test4",
                  "attributes": {
                    "vatNumber": 63826383
                  },
                  "roles": [
                    {
                      "code": "role-673f20jvsklwh",
                      "type": "ACCESS"
                    },
                    {
                      "code": "role-63nso3bs9ln",
                      "type": "ADMIN"
                    }
                  ]
                }
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/genericErrorSchema"
              examples:
                Invalid payload:
                  value:
                    error:
                      code: "TRANSPORT.INVALID_PAYLOAD"
                      ns: "TRANSPORT"
                      message: "Invalid payload."
                      status: 400
                Missing name:
                  value:
                    error:
                      code: "DATA.INVALID"
                      ns: "DATA"
                      message: "error.group.create.empty.displayName"
                      data:
                        field: "name"
                      status: 400
                Missing code:
                  value:
                    error:
                      code: "DATA.INVALID"
                      ns: "DATA"
                      message: "error.group.create.empty.code"
                      data:
                        field: "status"
                      status: 400
                Missing structureCode:
                  value:
                    error:
                      code: "DATA.INVALID"
                      ns: "DATA"
                      message: "error.group.empty.structureCode"
                      data:
                        field: "structureCode"
                      status: 400
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/genericErrorSchema"
              examples:
                Not authorised to create group:
                  value:
                    error:
                      code: "UNAUTHORIZED"
                      ns: "GLOBAL"
                      message: "Not authorized to create group"
                      status: 401
                Invalid/expired access token:
                  value:
                    error:
                      code: "AUTH.EXPIRED"
                      ns: "AUTH"
                      message: "Authorized access_code is expired"
                      status: 401
        "403":
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/genericErrorSchema"
              examples:
                Group already exists:
                  value:
                    error:
                      code: "FORBIDDEN"
                      ns: "GLOBAL"
                      message: "error.group.create.exist.code"
                      status: 403
        "404":
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/genericErrorSchema"
              examples:
                The provided value for structureCode is not valid:
                  value:
                    error:
                      code: "GROUP.NOT_FOUND"
                      ns: "GROUP"
                      message: "error.structure.notFound"
                      status: 404
                The provided value for groupParent is not valid:
                  value:
                    error:
                      code: "GROUP.NOT_FOUND"
                      ns: "GROUP"
                      message: "error.parentGroup.notFound"
                      status: 404
        "422":
          description: "Invalid data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/genericErrorSchema"
              examples:
                Used group attribute code is not configured for the structure:
                  value:
                    error:
                      code: "DATA.INVALID"
                      ns: "DATA"
                      message: "error.structure.groups.attribute.not.configured"
                      status: 422
                All roles need to have a code:
                  value:
                    error:
                      code: "DATA.INVALID"
                      ns: "DATA"
                      message: "error.structure.group.roles.empty.code"
                      status: 422
                All roles need to have a type:
                  value:
                    error:
                      code: "DATA.INVALID"
                      ns: "DATA"
                      message: "error.structure.group.roles.empty.roleType"
                      status: 422
                The added role does not exist or is outside of scope:
                  value:
                    error:
                      code: "DATA.INVALID"
                      ns: "DATA"
                      message: "error.structure.group.role.invalid"
                      status: 422
      security:
        - OAuth2: []
        - APIKey: []
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth2/OIDC authentication at the AS/OP that is integrated with RITM
      flows:
        authorizationCode:
          authorizationUrl: https://example-domain-uri.com/auth/oauth2.0/v1/authorize
          tokenUrl: https://example-domain-uri.com/auth/oauth2.0/v1/token
          scopes:
            workflow:invitation:admin:post: Allows to start invitation flow
    APIKey:
      type: http
      scheme: bearer
      bearerFormat: APIKey
  schemas:
    # Regular schemas
    genericErrorSchema:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            ns:
              type: string
            message:
              type: string
            data:
              type: object
              properties:
                field:
                  type: string
            status:
              type: integer
    groupCreateRequest:
      type: object
      properties:
        code:
          type: string
          description: The code corresponding to the group being created.
        name:
          type: string
          description: The name of the group.
        structureCode:
          type: string
          description: The code corresponding to the structure that the group belongs to.
        groupParent:
          type: string
          description: If there is a parent, the code of the parent group.
        attributes:
          type: object
          additionalProperties:
            type: string
            description: The code(s) for the attributes as defined for the structure
        roles:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              type:
                type: string
            required:
              - code
              - type
      required:
        - code
        - name
        - structureCode
