openapi: 3.0.3
info:
  title: Identity access management
  description: >
    This is an API intended for managing portal users, system users, domains, custom roles and access rights.
  license:
    name: Telenor Connexion Public License - v 1.0
    url: https://www.telenorconnexion.com
  termsOfService: https://www.telenorconnexion.com/terms-of-service
  contact:
    name: Telenor Connexion Support
    email: it-operations@telenorconnexion.com
  version: 2.1.0
servers:
  - url: https://api.iot.telenor.com/identity-access-management
tags:
  - name: Token Permissions
    description: Access token related information
  - name: Roles
    description: Information about roles
  - name: Access Rights
    description: Information about access rights
  - name: Domains
    description: Domain management
  - name: Portal Users
    description: Portal user management
  - name: System Users
    description: System user management
paths:
  /token-permissions:
    get:
      tags:
        - Token Permissions
      summary: Get permissions associated with an access token.
      description: |
        Returns authorization related information for the specified access token. This endpoint can be used by authorizers to determine whether a user is allowed to access an API or not. It can also be used by GUI portals to provide a better UX experience by hiding pages and buttons the user is not allowed to access.

        REST API authorizers should make use of the `permissions` property, which contains permissions grouped by resources. API authorizers must find the permissions associated with their resource and check for the presence of any required permissions when authorizing users. Permissions belonging to other resources should be discarded.

        The `solutions` property determines which solutions a user has access to and depends on which domain the user belongs to. REST API authorizers may combine specific `permissions` with `solutions` when determining whether a user is allowed to access an endpoint or not.

        GUI portal implementations wishing to provide better UX can use values present in `solutions`, `roles`, and/or `accessRights` to lock down functionality and hide content the user is not allowed to view. Note that this should be viewed as a UX improvement and NOT a substitute for API authorization checks. An API must always implement authorization checks based on which `permissions` a user has.

        It is encouraged to cache this response but not for too long. Refer to relevant security guidelines when determining cache time-to-live.

        If the token is invalid (e.g. if it has been revoked or expired) then a 401 response will be returned.
      responses:
        200:
          description: Contains all kinds of permissions associated with the access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/queryTokenPermissionsResponse'
        401: &401-error
          description: Invalid or missing access token (JWT).

  /portal-users:
    get:
      tags:
        - Portal Users
      summary: List all portal users
      description: Returns a list of all portal users according to supplied query parameters.
      parameters:
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/searchPortalUserQuery'
        - $ref: '#/components/parameters/filterDomainIdPortalUserQuery'
        - $ref: '#/components/parameters/filterDomainIdWithSubdomainsPortalUserQuery'
        - $ref: '#/components/parameters/filterRoleIdsPortalUserQuery'
      responses:
        200:
          description: Returns all portal users matching search/filters criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/queryAllPortalUsersResponse'
        400: &400-error
          $ref: '#/components/responses/Error400'
        401: *401-error
        403: &403-error
          description: Not authorized to access this resource.
        404: &404-error
          $ref: '#/components/responses/Error404'

  /domains/{id}/portal-users:
    post:
      tags:
        - Portal Users
      summary: Add new portal user
      description: Adds a portal user by onboarding it from an external identity provider.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
      requestBody:
        description: Definition of the portal user to add.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createPortalUserRequest'
      responses:
        201:
          description: The portal user was successfully added.
          headers:
            Location:
              $ref: '#/components/headers/Location'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error
        409:
          description: Portal user already exists.

    get:
      tags:
        - Portal Users
      summary: List domain portal users
      description: Returns a list of portal users according to supplied query parameters.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/searchPortalUserQuery'
      responses:
        200:
          description: Returns all portal users matching search criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/queryPortalUsersResponse'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}/portal-users/{portalUserId}:
    get:
      tags:
        - Portal Users
      summary: Get a specific portal user
      description: Get a specific portal user.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/portalUserIdInPath'
      responses:
        200:
          description: The portal user was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/queryPortalUserResponse'
        401: *401-error
        403: *403-error
        404: *404-error

    delete:
      tags:
        - Portal Users
      summary: Delete a portal user
      description: Delete a portal user.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/portalUserIdInPath'
      responses:
        204:
          description: The portal user was deleted.
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}/portal-users/{portalUserId}/enabled:
    put:
      tags:
        - Portal Users
      summary: Enables or disables a portal user
      description: Change a portal user's status. This determines whether a portal user can log in or not.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/portalUserIdInPath'
      requestBody:
        description: States whether to enable or disable the portal user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateUserEnabledRequest'
      responses:
        204:
          description: The portal user's status has been updated.
          headers:
            Content-Location:
              $ref: '#/components/headers/Content-Location'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}/portal-users/{portalUserId}/roles:
    put:
      tags:
        - Portal Users
      summary: Set roles for a portal user
      description: Overwrites the portal user's current roles with the provided roles. Roles are a collection of access rights and determine what resources (API endpoints) the portal user is able to access.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/portalUserIdInPath'
      requestBody:
        description: List of roles to assign to the portal user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateRolesForUserRequest'
      responses:
        204:
          description: The portal user's roles have been updated.
          headers:
            Content-Location:
              $ref: '#/components/headers/Content-Location'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}/portal-users/{portalUserId}/domain:
    put:
      tags:
        - Portal Users
      summary: Set domain for a portal user
      description: Overwrites the portal user's current domain with the provided domain.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/portalUserIdInPath'
      requestBody:
        description: Domain ID to assign to the portal user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateDomainForPortalUserRequest'
      responses:
        204:
          description: The portal user's domain has been updated.
          headers:
            Content-Location:
              $ref: '#/components/headers/Content-Location'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /system-users:
    get:
      tags:
        - System Users
      summary: List all system users
      description: Returns a list of detailed system users across your domains.
      responses:
        200:
          description: Returns all system users matching search criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/queryAllSystemUsersResponse'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error
  
  /domains/{id}/system-users:
    post:
      tags:
        - System Users
      summary: Create new system user
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
      requestBody:
        required: true
        description: Required data needed to create a system user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createSystemUserRequest'
      description: Create a new system user.
      responses:
        201:
          description: The system user was successfully created.
          headers:
            Location:
              $ref: '#/components/headers/Location'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error
        409:
          description: System user already exists.

    get:
      tags:
        - System Users
      summary: List domain system users
      description: Returns a list of system users according to supplied parameters.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
      responses:
        200:
          description: Returns all system users matching search criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/querySystemUsersResponse'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}/system-users/{systemUserId}:
    get:
      tags:
        - System Users
      summary: Get a specific system user.
      description: Get a specific system user.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/systemUserIdInPath'
      responses:
        200:
          description: The system user was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/systemUserDefinition'
        401: *401-error
        403: *403-error
        404: *404-error

    delete:
      tags:
        - System Users
      summary: Delete a system user
      description: Delete a system user.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/systemUserIdInPath'
      responses:
        204:
          description: The system user was successfully deleted.
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}/system-users/{systemUserId}/generate-client-secret:
    post:
      tags:
        - System Users
      summary: Generate a new client secret for a system user
      description: >-
        Generates a new client secret for the specified system user.
        Note that the old client secret will no longer be valid since it is replaced with
        the newly generated secret.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/systemUserIdInPath'
      responses:
        200:
          description: The system user's secret was successfully generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/querySystemUserSecretResponse'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}/system-users/{systemUserId}/client-secret:
    get:
      tags:
        - System Users
      summary: Get client secret for a system user
      description: Get client secret for a system user.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/systemUserIdInPath'
      responses:
        200:
          description: The system user's secret was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/querySystemUserSecretResponse'
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}/system-users/{systemUserId}/enabled:
    put:
      tags:
        - System Users
      summary: Enables or disables a system user
      description: >-
        Change a system user's status. This determines whether a system user can log in or
        not.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/systemUserIdInPath'
      requestBody:
        description: States whether to enable or disable the system user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateUserEnabledRequest'
      responses:
        204:
          description: The system user's status has been updated.
          headers:
            Content-Location:
              $ref: '#/components/headers/Content-Location'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}/system-users/{systemUserId}/roles:
    put:
      tags:
        - System Users
      summary: Set roles for a system user.
      description: >-
        Overwrites the system user's current roles with the provided roles.
        Roles are a collection of access rights and determine what resources (API endpoints) the system user is able to access.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
        - $ref: '#/components/parameters/systemUserIdInPath'
      requestBody:
        description: List of roles to assign to the system user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateRolesForUserRequest'
      responses:
        204:
          description: The system user's roles have been updated.
          headers:
            Content-Location:
              $ref: '#/components/headers/Content-Location'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains:
    post:
      tags:
        - Domains
      summary: Create new domain
      description: Creates a new domain.
      requestBody:
        description: Definition of the domain to add.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createDomainRequest'
      responses:
        201:
          description: The domain was successfully created.
          headers:
            Location:
              $ref: '#/components/headers/Location'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error
        409:
          description: Domain already exists.

    get:
      tags:
        - Domains
      summary: List domains
      description: Returns a list of domains according to supplied query parameters.
      parameters:
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/searchDomainQuery'
      responses:
        200:
          description: Returns all domains matching search criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/queryDomainsResponse'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /domains/{id}:
    get:
      tags:
        - Domains
      summary: Get a specific domain
      description: Get a specific domain.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
      responses:
        200:
          description: The domain was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/queryDomainResponse'
        401: *401-error
        403: *403-error
        404: *404-error

    patch:
      tags:
        - Domains
      summary: Update a specific domain
      description: Update one or more properties for a domain.
      parameters:
        - $ref: '#/components/parameters/domainUuidInPath'
      requestBody:
        description: Domain properties to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patchDomainRequest'
      responses:
        204:
          description: The domain was updated.
          headers:
            Content-Location:
              $ref: '#/components/headers/Content-Location'
        400: *400-error
        401: *401-error
        403: *403-error
        404: *404-error

  /access-rights:
    get:
      tags:
        - Access Rights
      summary: List access rights
      description: Lists all available access rights. Only access rights the user has are listed.
      responses:
        200:
          description: Returns all access rights.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accessRightsDefinition'
        401: *401-error
        403: *403-error
        404: *404-error

  /roles:
    get:
      tags:
        - Roles
      summary: List roles
      description: Lists all available roles. Only roles the user has are listed.
      responses:
        200:
          description: Returns all roles the user has permission to view.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rolesDefinition'
        401: *401-error
        403: *403-error
        404: *404-error

  /roles/{roleId}:
    get:
      tags:
        - Roles
      summary: Get a specific role
      description: Get a specific role.
      parameters:
        - $ref: '#/components/parameters/roleIdInPath'
      responses:
        200:
          description: The role was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/roleDetailedDefinition'
        401: *401-error
        403: *403-error
        404: *404-error

components:
  responses:
    Error400:
      description: Bad request. The server cannot process the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error400Body'

    Error404:
      description: Entity not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error404Body'

    Error500:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error500Body'

  headers:
    Content-Location:
      description: URL to the resource that got impacted by the request.
      schema:
        $ref: '#/components/schemas/HeaderUrl'

    Location:
      description: URL to the resource that got created.
      schema:
        $ref: '#/components/schemas/HeaderUrl'

  parameters:
    systemUserIdInPath:
      in: path
      name: systemUserId
      description: Identifies the system user.
      required: true
      schema:
        type: string
        format: uuid

    domainUuidInPath:
      in: path
      name: id
      description: Identifies the domain in Keycloak.
      required: true
      schema:
        type: string
        format: uuid

    portalUserIdInPath:
      in: path
      name: portalUserId
      description: Identifies the portal user.
      required: true
      schema:
        type: string
        format: uuid

    roleIdInPath:
      in: path
      name: roleId
      description: Identifies the role.
      required: true
      schema:
        $ref: '#/components/schemas/roleIdDefinition'

    limitQuery:
      in: query
      name: limit
      description: Specifies the maximum number of results to be returned by the server.
      schema:
        type: number
        minimum: 1
        maximum: 100
        default: 100

    offsetQuery:
      in: query
      name: offset
      description: Specifies how many results to skip. Used in conjunction with `limit` to achieve pagination.
      schema:
        type: number
        minimum: 0
        maximum: 1000000
        default: 0

    searchPortalUserQuery:
      in: query
      name: search
      description: Search string to filter portal users by. Applies to multiple portal user properties such as email, first name, and last name.
      schema:
        type: string
        minLength: 1
        maxLength: 256

    filterDomainIdPortalUserQuery:
      in: query
      name: domainId
      description: Domain ID filter to retrive users for a single domain.
      schema:
        $ref: '#/components/schemas/domainIdDefinition'

    filterDomainIdWithSubdomainsPortalUserQuery:
      in: query
      name: domainIdWithSubdomains
      description: Domain ID filter including child domains to retreive users from.
      schema:
        $ref: '#/components/schemas/domainIdDefinition'
    
    filterRoleIdsPortalUserQuery:
      in: query
      name: roleIds
      example: [3fa85f64-5717-4562-b3fc-2c963f66afa6]
      description: Filter portal users by role IDs.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/roleIdDefinition'

    searchDomainQuery:
      in: query
      name: search
      description: Search string to filter domains by.
      schema:
        type: string
        minLength: 1
        maxLength: 256

  schemas:
    ErrorResponse:
      description: Error message
      type: object
      properties:
        description:
          description: Human readable description of the error
          type: string
          example: Requested resource does not exist.
        errorCode:
          type: string
          ## TODO Update the error names and descriptions during implementation.
          description: |
            Following errors are defined for this service:

            ## 400 Bad Request Errors

            ### INVALID_REQUEST_BODY

            Request body is invalid. Must contain valid JSON.

            ### INVALID_EMAIL

            Invalid value for the property `email`. Must be a valid email.

            ### INVALID_CLIENT_ID_PREFIX

            Invalid value for the property `clientIdPrefix`. Allowed characters are A-Z, a-z, 0-9, as well as underscore (_) and hyphen (-). Client id must not be longer than 128 characters.

            ### NOT_ALLOWED_TO_MANAGE_SELF

            Not allowed to manage your own user.

            ### INVALID_USER_STATUS

            Invalid value for the property `enabled`. Boolean values are allowed.

            ### INVALID_SEARCH_VALUE

            Invalid value for the query parameter `search`. Most Unicode characters are allowed..

            ### INVALID_OFFSET_VALUE

            Invalid value for the query parameter `offset`. Number between 0 and 1000000 is allowed.

            ### INVALID_LIMIT_VALUE

            Invalid value for the query parameter `limit`. Number between 0 and 100 is allowed.

            ### INVALID_ROLES_ARRAY

            Invalid value for the property `roles`. Must be of type array ([]) containing between 0 and 100 roles.

            ### INVALID_SOLUTIONS_ARRAY

            Invalid value for the property `solutions`. Must be of type array ([]) containing between 0 and 100 solutions.

            ### INVALID_SOLUTION

            Invalid value for one or more entries in the `solutions` array. Alphabetic characters, numbers, and some special characters are allowed.

            ### INVALID_USER_ROLES

            Invalid content in property `roles`. Each role must contain property `id` with UUID formatting and property `type` specifying whether the role is `global` or `custom`.

            ### INVALID_SYSTEM_USER_ROLES

            Invalid content in property `roles`. Each role must contain property `id` with UUID formatting and property `type` with value `global`.

            ### INVALID_GLOBAL_ROLE

            At least one of the requested global roles is invalid.

            ### INVALID_NAME

            Invalid value for the property `name`. Alphabetic characters, numbers, and some special characters are allowed.

            ### INVALID_PHONE_NUMBER

            Invalid value for the property `phoneNumber`. Must be of type string containing between 4 and 20 numbers.

            ### INVALID_PARENT_DOMAIN_ID

            Invalid value for the property `parentId`. Must contain a string with UUID formatting.

            ### INVALID_DOMAIN_ID

            Invalid value for the property 'domainId'. Must contain a string.

            ### PARENT_DOMAIN_NOT_FOUND

            The domain specified in the property `parentId` could not be found.

            ## 401 Unauthorized Errors

            ### INVALID_TOKEN

            Access token is not valid.

            ## 403 Forbidden Errors

            ### FORBIDDEN_ERROR

            Not authorized to access this resource.

            ### FORBIDDEN_ROLE_UPDATE

            Forbidden operation since it would result in the addition or removal of a role the requesting user does not have themselves.

            ### FORBIDDEN_IDENTICAL_DOMAIN_UPDATE

            User already belongs to the specified domain.

            ### FORBIDDEN_SOLUTION

            Forbidden operation since it would result in the addition or removal of a solution the requesting user does not have themselves.

            ### FORBIDDEN_ROOT_DOMAIN_SOLUTIONS_UPDATE

            Not allowed to change solutions for root domain.

            ## 404 Not Found Errors

            ### RESOURCE_NOT_FOUND

            Requested resource does not exist.

            ## 409 Conflict Errors

            ### CONFLICT_ERROR

            Resource already exists.

            ## 500 Internal Server Errors

            ### SERVICE_ERROR

            Error occurred when communicating with another service. Please try again or contact your system administrator if this problem persists.

            ### ACCESS_TOKEN_ERROR

            Unexpected error with access token. Please try logging out and in again or contact your system administrator if this problem persists.

            ### CREATE_DOMAIN_ERROR

            Domain could not be created due to an unexpected internal error. Please try again or contact your system administrator if this problem persists.

            ## 503 Service Unavailable Errors

            ### CRITICAL_SERVICE_ERROR

            Unable to communicate with another service. Please try again or contact your system administrator if this problem persists.

          example: RESOURCE_NOT_FOUND
        timestamp:
          description: Epoch timestamp specifying when error occurred
          type: integer
          example: 1560954657369

    Error400Body:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - properties:
            description:
              example: Invalid parameter.
            errorCode:
              example: INVALID_REQUEST
    Error404Body:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'

    Error500Body:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - properties:
            description:
              example: Internal server error.
            errorCode:
              example: UNKNOWN_ERROR

    #Commonly used properties
    HeaderUrl:
      type: string
      format: url

    clientIdDefinition:
      description: Used to identify and log in as the system user. A client id has the format <clientIdPrefix>@<domainId>.
      type: string
      example: ordering-api-user@abcd1234-efgh1234

    clientIdPrefixDefinition:
      description: The client ID prefix is used to construct the complete client ID which will have the format <clientIdPrefix>@<domainId>. Each client ID prefix is unique for the domain it was created in.
      type: string
      example: ordering-api-user

    domainIdDefinition:
      description: Hierarchical identifier for a domain. Used to identify which domain a user belongs to and whether a user has access to a domain.
      type: string
      example: abcd1234-efgh1234

    systemUserIdDefinition:
      description: Id of the system user.
      type: string
      format: uuid

    userEnabledDefinition:
      description: Sets a user to active if true or inactive if false.
      type: boolean

    userCreatedTimestampDefinition:
      description: When the user was created, specified in ISO 8601.
      type: string
      format: date-time

    updateRolesDefinition:
      type: object
      description: Specifies which role to assign. Custom roles can only be assigned to portal users and must belong to the same domain as the portal user.
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/roleIdDefinition'

    updateRolesForUserRequest:
      description: Properties for updating roles.
      type: object
      required:
        - roles
      properties:
        roles:
          type: array
          items:
            $ref: '#/components/schemas/updateRolesDefinition'

    updateDomainForPortalUserRequest:
      description: Properties for updating a portal user's domain.
      type: object
      required:
        - domainId
      properties:
        domainId:
          $ref: '#/components/schemas/domainIdDefinition'

    usersDomainDefinition:
      description: Contains domain properties.
      type: object
      required:
        - id
        - name
      properties:
        id:
          $ref: '#/components/schemas/domainKeycloakIdDefinition'
        name:
          $ref: '#/components/schemas/domainNameDefinition'

    updateUserEnabledRequest:
      description: Properties for updating a user's status.
      type: object
      required:
        - enabled
      properties:
        enabled:
          $ref: '#/components/schemas/userEnabledDefinition'

    #Token permissions
    permissionsDefinition:
      description: List of permissions. Only the permission's name is listed
      type: array
      items:
        description: Name of the permission.
        type: string
        example: domains-read

    resourcePermissionsDefinition:
      description: Permissions sorted by the resource they belong to.
      type: object
      additionalProperties:
        $ref: '#/components/schemas/permissionsDefinition'
      example:
        user-management-resource: [domains-read]
        iot-complete-resource: [subscription-monitoring]

    queryTokenPermissionsResponse:
      description: Roles and domain information for a user's access token.
      type: object
      required:
        - domainId
        - roles
        - accessRights
        - solutions
        - permissions
      properties:
        domainId:
          $ref: '#/components/schemas/domainIdDefinition'
        roles:
          $ref: '#/components/schemas/roleNamesList'
        accessRights:
          $ref: '#/components/schemas/accessRightNamesList'
        solutions:
          $ref: '#/components/schemas/solutionNamesList'
        permissions:
          $ref: '#/components/schemas/resourcePermissionsDefinition'

    #Portal users
    portalUserIdDefinition:
      description: Id of the portal user.
      type: string
      format: uuid

    portalUserFirstNameDefinition:
      description: First name of the portal user.
      type: string
      example: John

    portalUserLastNameDefinition:
      description: Last name of the portal user.
      type: string
      example: Doe

    portalUserEmailDefinition:
      description: The email address of the portal user.
      type: string
      minLength: 5
      maxLength: 254
      example: john.doe@example.com

    portalUserPhoneNumberDefinition:
      description: The phone number of the portal user.
      type: string
      minLength: 4
      maxLength: 20
      example: 460760000001

    queryPortalUsersDefinition:
      description: Contains portal user properties.
      type: object
      required:
        - id
        - createdTimestamp
        - enabled
        - firstName
        - lastName
        - email
        - domainId
      properties:
        id:
          $ref: '#/components/schemas/portalUserIdDefinition'
        createdTimestamp:
          $ref: '#/components/schemas/userCreatedTimestampDefinition'
        enabled:
          $ref: '#/components/schemas/userEnabledDefinition'
        firstName:
          $ref: '#/components/schemas/portalUserFirstNameDefinition'
        lastName:
          $ref: '#/components/schemas/portalUserLastNameDefinition'
        email:
          $ref: '#/components/schemas/portalUserEmailDefinition'
        phoneNumber:
          $ref: '#/components/schemas/portalUserPhoneNumberDefinition'
        domainId:
          $ref: '#/components/schemas/domainIdDefinition'

    queryPortalUsersResponse:
      description: Contains list of domain portal users.
      type: array
      items:
        $ref: '#/components/schemas/queryPortalUsersDefinition'
    
    queryAllPortalUsersResponse:
      description: Contains list of all portal users.
      type: array
      items:
        $ref: '#/components/schemas/queryPortalUserResponse'

    queryPortalUserResponse:
      description: Portal user with roles and domain information.
      type: object
      required:
        - id
        - createdTimestamp
        - enabled
        - firstName
        - lastName
        - email
        - domainId
        - roles
        - domain
      properties:
        id:
          $ref: '#/components/schemas/portalUserIdDefinition'
        createdTimestamp:
          $ref: '#/components/schemas/userCreatedTimestampDefinition'
        enabled:
          $ref: '#/components/schemas/userEnabledDefinition'
        firstName:
          $ref: '#/components/schemas/portalUserFirstNameDefinition'
        lastName:
          $ref: '#/components/schemas/portalUserLastNameDefinition'
        email:
          $ref: '#/components/schemas/portalUserEmailDefinition'
        phoneNumber:
          $ref: '#/components/schemas/portalUserPhoneNumberDefinition'
        domainId:
          $ref: '#/components/schemas/domainIdDefinition'
        roles:
          $ref: '#/components/schemas/rolesDefinition'
        domain:
          $ref: '#/components/schemas/usersDomainDefinition'

    createPortalUserRequest:
      description: Properties for creating a portal user.
      type: object
      required:
        - enabled
        - email
      properties:
        enabled:
          $ref: '#/components/schemas/userEnabledDefinition'
        email:
          $ref: '#/components/schemas/portalUserEmailDefinition'
        phoneNumber:
          $ref: '#/components/schemas/portalUserPhoneNumberDefinition'

    #Access Rights
    accessRightIdDefinition:
      description: Id of the access right.
      type: string
      format: uuid

    accessRightNameDefinition:
      description: Name of the access right.
      type: string
      example: device-ordering

    accessRightDefinition:
      description: Contains access right properties.
      type: object
      required:
        - id
        - name
        - description
      properties:
        id:
          $ref: '#/components/schemas/accessRightIdDefinition'
        name:
          $ref: '#/components/schemas/accessRightNameDefinition'
        description:
          description: Description of the access right.
          type: string
          example: Access right for device ordering.

    accessRightNamesList:
      description: Contains a list of access rights. Only the access right's name is listed.
      type: array
      items:
        $ref: '#/components/schemas/accessRightNameDefinition'

    accessRightsDefinition:
      description: Contains a list of access rights.
      type: array
      items:
        $ref: '#/components/schemas/accessRightDefinition'

    #System Users
    systemUsersDefinition:
      description: Contains system user properties.
      type: object
      required:
        - id
        - clientId
        - enabled
        - domainId
      properties:
        id:
          $ref: '#/components/schemas/systemUserIdDefinition'
        clientId:
          $ref: '#/components/schemas/clientIdDefinition'
        enabled:
          $ref: '#/components/schemas/userEnabledDefinition'
        domainId:
          $ref: '#/components/schemas/domainIdDefinition'

    systemUserDefinition:
      description: Contains system user properties.
      type: object
      required:
        - id
        - clientId
        - enabled
        - domainId
        - roles
        - domain
        - accessRights
      properties:
        id:
          $ref: '#/components/schemas/systemUserIdDefinition'
        clientId:
          $ref: '#/components/schemas/clientIdDefinition'
        enabled:
          $ref: '#/components/schemas/userEnabledDefinition'
        domainId:
          $ref: '#/components/schemas/domainIdDefinition'
        roles:
          $ref: '#/components/schemas/rolesDefinition'
        domain:
          $ref: '#/components/schemas/usersDomainDefinition'

    querySystemUserSecretResponse:
      description: System user's client secret
      type: object
      required:
        - clientSecret
      properties:
        clientSecret:
          description: The client secret used to log in as the system user.
          type: string

    queryAllSystemUsersResponse:
      description: Contains list of detailed system users.
      type: array
      items:
        $ref: '#/components/schemas/systemUserDefinition'
    
    querySystemUsersResponse:
      description: Contains list of system users.
      type: array
      items:
        $ref: '#/components/schemas/systemUsersDefinition'

    createSystemUserRequest:
      description: Properties for creating a system user.
      type: object
      required:
        - clientIdPrefix
        - enabled
      properties:
        clientIdPrefix:
          $ref: '#/components/schemas/clientIdPrefixDefinition'
        enabled:
          $ref: '#/components/schemas/userEnabledDefinition'

    #Domains
    domainKeycloakIdDefinition:
      description: Id of the domain in Keycloak. Only used in this API, not to be confused with domainId.
      type: string
      format: uuid

    domainNameDefinition:
      description: Name of the domain.
      type: string
      example: Acme

    parentDomainDefinition:
      description: Id of the parent domain. If there is no parent domain this value will be `null`.
      type: string
      format: uuid
      nullable: true

    domainDefinition:
      description: Contains domain properties.
      type: object
      required:
        - id
        - name
        - domainId
        - parentId
      properties:
        id:
          $ref: '#/components/schemas/domainKeycloakIdDefinition'
        name:
          $ref: '#/components/schemas/domainNameDefinition'
        domainId:
          $ref: '#/components/schemas/domainIdDefinition'
        parentId:
          $ref: '#/components/schemas/parentDomainDefinition'
        solutions:
          $ref: '#/components/schemas/solutionNamesList'

    createDomainRequest:
      description: Properties for creating a domain.
      type: object
      required:
        - name
        - parentId
        - solutions
      properties:
        name:
          $ref: '#/components/schemas/domainNameDefinition'
        parentId:
          $ref: '#/components/schemas/parentDomainDefinition'
        solutions:
          $ref: '#/components/schemas/solutionNamesList'

    patchDomainRequest:
      description: Properties available to update for a domain. One or more properties can be specified.
      type: object
      properties:
        name:
          $ref: '#/components/schemas/domainNameDefinition'
        solutions:
          $ref: '#/components/schemas/solutionNamesList'

    queryDomainsResponse:
      description: Contains list of domains.
      type: array
      items:
        $ref: '#/components/schemas/domainDefinition'

    queryDomainResponse:
      $ref: '#/components/schemas/domainDefinition'

    #Domain solutions
    solutionName:
      description: Specifies a solution bought by a domain.
      type: string
      example: iot-complete

    solutionNamesList:
      description: Contains list of solutions.
      type: array
      items:
        $ref: '#/components/schemas/solutionName'

    #Roles
    roleIdDefinition:
      description: Identifies the role.
      type: string
      format: uuid

    roleNameDefinition:
      description: Name of the role.
      type: string
      example: Subscription ordering

    roleDescriptionDefinition:
      description: Description of the role.
      type: string
      example: Allows user to order new subscriptions and follow up existing orders.

    roleNamesList:
      description: Contains list of roles. Only the role's name is displayed.
      type: array
      items:
        $ref: '#/components/schemas/roleNameDefinition'

    rolesDefinition:
      description: Contains list of roles.
      type: array
      items:
        $ref: '#/components/schemas/roleOverviewDefinition'

    roleOverviewDefinition:
      description: Contains role properties.
      type: object
      required:
        - id
        - name
        - description
      properties:
        id:
          $ref: '#/components/schemas/roleIdDefinition'
        name:
          $ref: '#/components/schemas/roleNameDefinition'
        description:
          $ref: '#/components/schemas/roleDescriptionDefinition'

    roleDetailedDefinition:
      description: Contains all role properties.
      type: object
      required:
        - id
        - name
        - description
        - accessRights
      properties:
        id:
          $ref: '#/components/schemas/roleIdDefinition'
        name:
          $ref: '#/components/schemas/roleNameDefinition'
        description:
          $ref: '#/components/schemas/roleDescriptionDefinition'
        accessRights:
          $ref: '#/components/schemas/accessRightsDefinition'

  securitySchemes:
    oAuth2:
      type: oauth2
      flows:
        authorizationCode:
          tokenUrl: /auth/realms/telenor-iot/protocol/openid-connect/token
          authorizationUrl: /auth/realms/telenor-iot/protocol/openid-connect/auth
          scopes:
            openid: openid
        clientCredentials:
          tokenUrl: /auth/realms/telenor-iot/protocol/openid-connect/token
          scopes:
            openid: openid

security:
  - oAuth2: [openid]