Humanitec API — UserRole

naftiko: 1.0.0-alpha2
info:
  label: Humanitec API — UserRole
  description: 'Humanitec API — UserRole. 16 operations. Lead operation: List Users or Groups with roles in an App. Self-contained
    Naftiko capability covering one Humanitec business surface.'
  tags:
  - Humanitec
  - UserRole
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    HUMANITEC_API_KEY: HUMANITEC_API_KEY
capability:
  consumes:
  - type: http
    namespace: humanitec-userrole
    baseUri: https://api.humanitec.io
    description: Humanitec API — UserRole business capability. Self-contained, no shared references.
    resources:
    - name: orgs-orgId-apps-appId-users
      path: /orgs/{orgId}/apps/{appId}/users
      operations:
      - name: listuserrolesinapp
        method: GET
        description: List Users or Groups with roles in an App
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createuserroleinapp
        method: POST
        description: Adds a User or a Group to an Application with a Role
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-apps-appId-users-userId
      path: /orgs/{orgId}/apps/{appId}/users/{userId}
      operations:
      - name: getuserroleinapp
        method: GET
        description: Get the role of a User or a Group on an Application
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deleteuserroleinapp
        method: DELETE
        description: Remove the role of a User or a Group on an Application
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updateuserroleinapp
        method: PATCH
        description: Update the role of a User or a Group on an Application
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-env-types-envType-users
      path: /orgs/{orgId}/env-types/{envType}/users
      operations:
      - name: listuserrolesinenvtype
        method: GET
        description: List Users and Groups with roles in an Environment Type
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createuserroleinenvtype
        method: POST
        description: Adds a User or a Group to an Environment Type with a Role
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-env-types-envType-users-userId
      path: /orgs/{orgId}/env-types/{envType}/users/{userId}
      operations:
      - name: getuserroleinenvtype
        method: GET
        description: Get the role of a User or a Group on an Environment Type
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deleteuserroleinenvtype
        method: DELETE
        description: Remove the role of a User or a Group on an Environment Type
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updateuserroleinenvtype
        method: PATCH
        description: Update the role of a User or a Group on an Environment Type
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-invitations
      path: /orgs/{orgId}/invitations
      operations:
      - name: createinviteinorg
        method: POST
        description: Invites a user to an Organization with a specified role.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-users
      path: /orgs/{orgId}/users
      operations:
      - name: listuserrolesinorg
        method: GET
        description: List Users and Groups with roles in an Organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: orgs-orgId-users-userId
      path: /orgs/{orgId}/users/{userId}
      operations:
      - name: getuserroleinorg
        method: GET
        description: Get the role of a User or a Group on an Organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deleteuserroleinorg
        method: DELETE
        description: Remove the role of a User or a Group on an Organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updateuserroleinorg
        method: PATCH
        description: Update the role of a User or a Group on an Organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-users-userId-perms
      path: /orgs/{orgId}/users/{userId}/perms
      operations:
      - name: getsubjectpermsinorg
        method: GET
        description: Get the permissions of a User or Group on the objects in an Organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    namespace: humanitec-userrole-rest
    port: 8080
    description: REST adapter for Humanitec API — UserRole. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/orgs/{orgid}/apps/{appid}/users
      name: orgs-orgid-apps-appid-users
      description: REST surface for orgs-orgId-apps-appId-users.
      operations:
      - method: GET
        name: listuserrolesinapp
        description: List Users or Groups with roles in an App
        call: humanitec-userrole.listuserrolesinapp
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createuserroleinapp
        description: Adds a User or a Group to an Application with a Role
        call: humanitec-userrole.createuserroleinapp
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/apps/{appid}/users/{userid}
      name: orgs-orgid-apps-appid-users-userid
      description: REST surface for orgs-orgId-apps-appId-users-userId.
      operations:
      - method: GET
        name: getuserroleinapp
        description: Get the role of a User or a Group on an Application
        call: humanitec-userrole.getuserroleinapp
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleteuserroleinapp
        description: Remove the role of a User or a Group on an Application
        call: humanitec-userrole.deleteuserroleinapp
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: updateuserroleinapp
        description: Update the role of a User or a Group on an Application
        call: humanitec-userrole.updateuserroleinapp
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/env-types/{envtype}/users
      name: orgs-orgid-env-types-envtype-users
      description: REST surface for orgs-orgId-env-types-envType-users.
      operations:
      - method: GET
        name: listuserrolesinenvtype
        description: List Users and Groups with roles in an Environment Type
        call: humanitec-userrole.listuserrolesinenvtype
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createuserroleinenvtype
        description: Adds a User or a Group to an Environment Type with a Role
        call: humanitec-userrole.createuserroleinenvtype
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/env-types/{envtype}/users/{userid}
      name: orgs-orgid-env-types-envtype-users-userid
      description: REST surface for orgs-orgId-env-types-envType-users-userId.
      operations:
      - method: GET
        name: getuserroleinenvtype
        description: Get the role of a User or a Group on an Environment Type
        call: humanitec-userrole.getuserroleinenvtype
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleteuserroleinenvtype
        description: Remove the role of a User or a Group on an Environment Type
        call: humanitec-userrole.deleteuserroleinenvtype
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: updateuserroleinenvtype
        description: Update the role of a User or a Group on an Environment Type
        call: humanitec-userrole.updateuserroleinenvtype
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/invitations
      name: orgs-orgid-invitations
      description: REST surface for orgs-orgId-invitations.
      operations:
      - method: POST
        name: createinviteinorg
        description: Invites a user to an Organization with a specified role.
        call: humanitec-userrole.createinviteinorg
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/users
      name: orgs-orgid-users
      description: REST surface for orgs-orgId-users.
      operations:
      - method: GET
        name: listuserrolesinorg
        description: List Users and Groups with roles in an Organization
        call: humanitec-userrole.listuserrolesinorg
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/users/{userid}
      name: orgs-orgid-users-userid
      description: REST surface for orgs-orgId-users-userId.
      operations:
      - method: GET
        name: getuserroleinorg
        description: Get the role of a User or a Group on an Organization
        call: humanitec-userrole.getuserroleinorg
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleteuserroleinorg
        description: Remove the role of a User or a Group on an Organization
        call: humanitec-userrole.deleteuserroleinorg
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: updateuserroleinorg
        description: Update the role of a User or a Group on an Organization
        call: humanitec-userrole.updateuserroleinorg
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/users/{userid}/perms
      name: orgs-orgid-users-userid-perms
      description: REST surface for orgs-orgId-users-userId-perms.
      operations:
      - method: GET
        name: getsubjectpermsinorg
        description: Get the permissions of a User or Group on the objects in an Organization
        call: humanitec-userrole.getsubjectpermsinorg
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: humanitec-userrole-mcp
    port: 9090
    transport: http
    description: MCP adapter for Humanitec API — UserRole. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: list-users-groups-roles-app
      description: List Users or Groups with roles in an App
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-userrole.listuserrolesinapp
      outputParameters:
      - type: object
        mapping: $.
    - name: adds-user-group-application-role
      description: Adds a User or a Group to an Application with a Role
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: humanitec-userrole.createuserroleinapp
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-role-user-group-application
      description: Get the role of a User or a Group on an Application
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-userrole.getuserroleinapp
      outputParameters:
      - type: object
        mapping: $.
    - name: remove-role-user-group-application
      description: Remove the role of a User or a Group on an Application
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: humanitec-userrole.deleteuserroleinapp
      outputParameters:
      - type: object
        mapping: $.
    - name: update-role-user-group-application
      description: Update the role of a User or a Group on an Application
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: humanitec-userrole.updateuserroleinapp
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-users-and-groups-roles
      description: List Users and Groups with roles in an Environment Type
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-userrole.listuserrolesinenvtype
      outputParameters:
      - type: object
        mapping: $.
    - name: adds-user-group-environment-type
      description: Adds a User or a Group to an Environment Type with a Role
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: humanitec-userrole.createuserroleinenvtype
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-role-user-group-environment
      description: Get the role of a User or a Group on an Environment Type
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-userrole.getuserroleinenvtype
      outputParameters:
      - type: object
        mapping: $.
    - name: remove-role-user-group-environment
      description: Remove the role of a User or a Group on an Environment Type
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: humanitec-userrole.deleteuserroleinenvtype
      outputParameters:
      - type: object
        mapping: $.
    - name: update-role-user-group-environment
      description: Update the role of a User or a Group on an Environment Type
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: humanitec-userrole.updateuserroleinenvtype
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: invites-user-organization-specified-role
      description: Invites a user to an Organization with a specified role.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: humanitec-userrole.createinviteinorg
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-users-and-groups-roles-2
      description: List Users and Groups with roles in an Organization
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-userrole.listuserrolesinorg
      outputParameters:
      - type: object
        mapping: $.
    - name: get-role-user-group-organization
      description: Get the role of a User or a Group on an Organization
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-userrole.getuserroleinorg
      outputParameters:
      - type: object
        mapping: $.
    - name: remove-role-user-group-organization
      description: Remove the role of a User or a Group on an Organization
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: humanitec-userrole.deleteuserroleinorg
      outputParameters:
      - type: object
        mapping: $.
    - name: update-role-user-group-organization
      description: Update the role of a User or a Group on an Organization
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: humanitec-userrole.updateuserroleinorg
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-permissions-user-group-objects
      description: Get the permissions of a User or Group on the objects in an Organization
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-userrole.getsubjectpermsinorg
      outputParameters:
      - type: object
        mapping: $.