Aiven Groups API

openapi: 3.2.0
info:
  contact:
    email: support@aiven.io
    name: Aiven support team
    url: https://aiven.io/support-services
  title: Aiven API Documentation Groups API
  version: v1
  x-logo:
    altText: Aiven logo
    backgroundColor: '#fafafa'
    href: https://api.aiven.io/doc
    url: https://aiven.io/assets/img/aiven-logo.png
  description: '# Introduction


    Direct link to openapi.json for use with external tools


    Aiven is a modern fully-managed open source data platform for streaming, storing, and analyzing data on any public cloud.'
servers:
- url: https://api.aiven.io/v1
tags:
- name: Groups
  x-displayName: Groups
paths:
  /organization/{organization_id}/user-groups:
    post:
      summary: Create a group
      tags:
      - Groups
      operationId: UserGroupCreate
      description: Create a new user group in an organization
      parameters:
      - $ref: '#/components/parameters/organization_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserGroupCreateRequestBody'
            example:
              description: The group of admins for the organization
              user_group_name: Admin Users
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupCreateResponse'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:write
    get:
      summary: List groups
      tags:
      - Groups
      operationId: UserGroupsList
      description: List all user groups within an organization
      parameters:
      - $ref: '#/components/parameters/organization_id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupsListResponse'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:read
  /organization/{organization_id}/user-groups/{user_group_id}:
    delete:
      summary: Delete a group
      tags:
      - Groups
      operationId: UserGroupDelete
      description: Delete a user group from an organization
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/user_group_id'
      responses:
        '204':
          description: Delete a group
          content: {}
        '409':
          description: Request conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - resource_managed_by_scim
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'resource_managed_by_scim: Cannot perform operation on SCIM managed resource'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:write
    get:
      summary: Retrieve a group
      tags:
      - Groups
      operationId: UserGroupGet
      description: Retrieve the details of a user group
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/user_group_id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupGetResponse'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:read
    patch:
      summary: Update a group
      tags:
      - Groups
      operationId: UserGroupUpdate
      description: Update details of a user group
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/user_group_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserGroupUpdateRequestBody'
            example:
              description: The group of admins for the organization
              user_group_name: Admin Users
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupUpdateResponse'
        '409':
          description: Request conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - resource_managed_by_scim
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'resource_managed_by_scim: Cannot perform operation on SCIM managed resource'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:write
  /organization/{organization_id}/user-groups/{user_group_id}/members:
    get:
      summary: List group members
      tags:
      - Groups
      operationId: UserGroupMemberList
      description: List members of a user group
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/user_group_id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupMemberListResponse'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:read
    patch:
      summary: Add or remove group members
      tags:
      - Groups
      operationId: UserGroupMembersUpdate
      description: Add or remove members of a user group
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/user_group_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserGroupMembersUpdateRequestBody'
            example:
              member_ids:
              - uas3l323kj
              operation: add_members
      responses:
        '204':
          description: Add or remove group members
          content: {}
        '409':
          description: Request conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - resource_managed_by_scim
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'resource_managed_by_scim: Cannot perform operation on SCIM managed resource'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:write
components:
  schemas:
    UserGroupMemberListResponse:
      type: object
      description: UserGroupMemberListResponse
      properties:
        members:
          type: array
          description: User group members
          items:
            type: object
            properties:
              last_activity_time:
                type: string
                maxLength: 36
                description: Last Activity Time
              user_id:
                type: string
                description: User ID
              user_info:
                type: object
                description: OrganizationUserInfo
                properties:
                  city:
                    type: string
                    maxLength: 512
                    description: City
                  country:
                    type: string
                    description: Country
                  create_time:
                    type: string
                    maxLength: 36
                    description: Creation time
                  department:
                    type: string
                    description: Department
                  is_application_user:
                    type: boolean
                    description: Is Application User
                  job_title:
                    type: string
                    description: Job Title
                  managed_by_scim:
                    type: boolean
                    description: Managed By Scim
                  managing_organization_id:
                    type: string
                    maxLength: 36
                    description: Managing Organization ID
                  real_name:
                    type: string
                    maxLength: 256
                    description: Real Name
                  state:
                    type: string
                    description: State
                  user_email:
                    type: string
                    maxLength: 254
                    description: User Email
                required:
                - create_time
                - is_application_user
                - managed_by_scim
                - real_name
                - state
                - user_email
            required:
            - user_id
            - user_info
      required:
      - members
    UserGroupGetResponse:
      type: object
      description: UserGroupGetResponse
      properties:
        create_time:
          type: string
          maxLength: 36
          description: User group creation time
        description:
          type: string
          maxLength: 4096
          description: Description
        managed_by_scim:
          type: boolean
          description: Managed By Scim
        update_time:
          type: string
          maxLength: 36
          description: User group last update time
        user_group_id:
          type: string
          maxLength: 36
          description: User Group ID
        user_group_name:
          type: string
          maxLength: 128
          description: User Group Name
      required:
      - create_time
      - description
      - managed_by_scim
      - update_time
      - user_group_id
      - user_group_name
    UserGroupsListResponse:
      type: object
      description: UserGroupsListResponse
      properties:
        user_groups:
          type: array
          description: User Groups
          items:
            type: object
            properties:
              create_time:
                type: string
                maxLength: 36
                description: User group creation time
              description:
                type: string
                maxLength: 4096
                description: Description
              managed_by_scim:
                type: boolean
                description: Managed By Scim
              member_count:
                type: integer
                description: Member Count
              update_time:
                type: string
                maxLength: 36
                description: User group last update time
              user_group_id:
                type: string
                maxLength: 36
                description: User Group ID
              user_group_name:
                type: string
                maxLength: 128
                description: User Group Name
            required:
            - create_time
            - description
            - managed_by_scim
            - member_count
            - update_time
            - user_group_id
            - user_group_name
      required:
      - user_groups
    UserGroupMembersUpdateRequestBody:
      type: object
      description: UserGroupMembersUpdateRequestBody
      properties:
        member_ids:
          type: array
          maxItems: 1024
          description: List of user IDs to apply the operation on
          items:
            type: string
        operation:
          type: string
          description: An enumeration.
          title: Operation to be performed on the group
          enum:
          - add_members
          - remove_members
      required:
      - member_ids
      - operation
    UserGroupCreateRequestBody:
      type: object
      description: UserGroupCreateRequestBody
      properties:
        description:
          type: string
          maxLength: 4096
          description: Description
        user_group_name:
          type: string
          maxLength: 128
          description: User Group Name
      required:
      - description
      - user_group_name
    UserGroupUpdateRequestBody:
      type: object
      description: UserGroupUpdateRequestBody
      properties:
        description:
          type: string
          maxLength: 4096
          description: Description
        user_group_name:
          type: string
          maxLength: 128
          description: User Group Name
    UserGroupUpdateResponse:
      type: object
      description: UserGroupUpdateResponse
      properties:
        create_time:
          type: string
          maxLength: 36
          description: User group creation time
        description:
          type: string
          maxLength: 4096
          description: Description
        managed_by_scim:
          type: boolean
          description: Managed By Scim
        update_time:
          type: string
          maxLength: 36
          description: User group last update time
        user_group_id:
          type: string
          maxLength: 36
          description: User Group ID
        user_group_name:
          type: string
          maxLength: 128
          description: User Group Name
      required:
      - create_time
      - description
      - managed_by_scim
      - update_time
      - user_group_id
      - user_group_name
    UserGroupCreateResponse:
      type: object
      description: UserGroupCreateResponse
      properties:
        create_time:
          type: string
          maxLength: 36
          description: User group creation time
        description:
          type: string
          maxLength: 4096
          description: Description
        managed_by_scim:
          type: boolean
          description: Managed By Scim
        update_time:
          type: string
          maxLength: 36
          description: User group last update time
        user_group_id:
          type: string
          maxLength: 36
          description: User Group ID
        user_group_name:
          type: string
          maxLength: 128
          description: User Group Name
      required:
      - create_time
      - description
      - managed_by_scim
      - update_time
      - user_group_id
      - user_group_name
  parameters:
    organization_id:
      in: path
      name: organization_id
      description: ID of an organization
      schema:
        type: string
      required: true
    user_group_id:
      in: path
      name: user_group_id
      description: ID of the user group
      schema:
        type: string
      required: true
  securitySchemes:
    tokenAuth:
      description: 'Header should be of the format `authorization: aivenv1 <TOKEN>`. Tokens can be obtained from [your Aiven profile page](https://console.aiven.io/profile/auth)'
      scheme: bearer
      type: http
    oauth2:
      type: oauth2
      description: OAuth2 security scheme
      flows:
        authorizationCode:
          authorizationUrl: https://console.aiven.io/oauth/authorize
          tokenUrl: https://api.aiven.io/v1/oauth2/token
          scopes:
            all: Provide full access to the API
            accounts: Allow enumerating and reading accounts configuration
            accounts:read: Allow modifying account configuration
            accounts:write: Provides full access to authentication related API
            authentication: Provides full access to authentication related API
            authentication:read: Allow reading authentication related configuration on resources (user profile, accounts)
            authentication:write: Allow modifying authentication related configurations on resources (user profile, accounts)
            billing: Provide full access to billing APIs
            billing:read: Allow reading billing information and configuration
            billing:write: Allow writing billing configuration
            payments: Provide full access to payment method APIs
            payments:read: Allow reading the payment method configurations
            payments:write: Allows writing payment method configuration
            privatelink: Provide full access to private link APIs
            privatelink:read: Allow enumerating and reading private link items and configurations
            privatelink:write: Allow writing (creating, modifying, deleting) private link items
            projects: Provide full access to projects APIs
            projects:read: Allow enumerating projects and reading their configuration
            projects:write: Allow writing (creating, modifying, deleting) projects
            scim: Provide full access to SCIM operations
            scim:read: Allow reading SCIM endpoints
            scim:write: Allow writing (modifying) SCIM endpoints
            services: Provide full access to services APIs
            services:read: Allow enumerating services and reading their configuration
            services:write: Allow writing (creating, modifying, deleting) services
            static_ips: Provide full access to static IPs APIs
            static_ips:read: Allow enumerating and reading static IP items and configurations
            static_ips:write: Allow writing (creating, modifying, deleting) static IP items
            tickets: Provide full access to support ticket APIs
            tickets:read: Allow enumerating and reading support tickets
            tickets:write: Allow writing (creating, modifying) support tickets
            user: Provide full access to user profile APIs
            user:read: Allow reading user profile and configuration
            user:write: Allow writing (modifying) user profile and configuration
externalDocs:
  description: Aiven CLI client
  url: https://github.com/aiven/aiven-client